10 ms·

So 30% of my current job is writing technical user guides for large, custom, automated research systems (the rest is design and development of those systems).

So 30% of my current job is writing technical user guides for large, custom, automated research systems (the rest is design and development of those systems). Each one is slightly different, and so needs its own guide. We currently are stuck using Word b/c it's so fast. Yes it's ugly. Yes it's a pain to work with sometimes. But I haven't found anything that's faster to produce these docs with. The reason we haven't switched to html, latex, or xml etc... is because I haven't found a typesetting program that is as easy to drag and drop images into and out of. Each guide has 30+ images on average. I _need_ that interface to be drag and drop otherwise it's too tedious to write the guide. The formatting of the text I'd love to do in some sort of markup language, but the images have to be dead simple. Short version: Anyone know of a typsetting solution with some markup language, version control, print to PDF happen at click of a button, and drag and drop images?

tambourine_man 11y ago
In Vim, I usually type <img src="images/… and AutoComplPop[1] sets in, showing all files in that directory. As long as they have a descriptive name, it's probably easier/faster/more reliable than drag and drop. In fact, I actually type img ctrl-E, which expands to the tag above and places cursor at the right place.[2] I know other editor have similar features, so it might be an alternative [1] http://www.vim.org/scripts/script.php?script_id=1879 [2] https://github.com/rstacruz/sparkup
ian97531 11y ago
Try a product called Habitat made by a company called Inkling. https://www.inkling.com/inspiration/ https://www.inkling.com/inspiration/ https://www.inkling.com/habitat/ https://www.inkling.com/habitat/
- rubidium 11y ago
  looks promising! Definitely attacking the same problem.
rhythmvs 11y ago
That’s exactly the sort of use case we are focussing on and building our automated typesetting service for.¹ You’ll probably also benefit from file inclusions so that you can keep a library of text snippets, with variables, keeping them versioned separately, and which you can then re-use and assemble to form a new, slightly different manual, with the variables automatically populated at typesetting time. Could you be more specific on the problem you’re facing with placing images? Is it that there are like hundreds of them, for which you would want to have created the references (and ![Caption](syntax)) automatically, because typing out the file paths manually is too tedious? That is doable, although it would be more of a drag-and-drop feature to be implemented by a dedicated Markdown editor, or an ST plugin. Or would you like to have more fine-grained control over floats, sizing and placement of the images relative to their place in the text narrative? For which a WYSIWYG interface is indeed more well suited, re: many document author’s gripe with TeX’s figure placement. ¹ http://textus.io/ http://textus.io/
- rubidium 11y ago
  Glad to hear it. Here's some bullet point thoughts: 1) Workflow needs to be uber-fast and not require saving/naming the images (at least at the user level, the program will of course). Many images are screen shots from SW installs. Workflow goes: Run SW in VM-> screenshot portion of interest -> Copy+Paste into word doc. I never even save the image in that case. The rest of the images are photos of HW. I just want to drag and drop into the document, not rename them all and move them to a same folder with the document. The document/CMS/program should take care of that all for me (like Word does). 2) I do need the text and images to match better and be more WYSIWYG. Location is more important than aesthetics for a guide. It cannot be the abomination that LaTeX is. LaTeX figures are terrible to work with (and that's having published multiple academic papers + PhD thesis in LaTeX). Sizing is less important (that can be [width=x, height=y]). 3) Variables/snippets: Libraries of text snippets and variables is what we do quite a bit of. Right now with a few kludged together macros and custom Word doc properties. Lots of docs go "Run the <SW install name> for <device>" with <> items defined at document level. Sounds like you do this, and it's probably better than how word does :) sorry for dumping on ya, but I'm excited to find people working in this space. It's something I feel like there should be better tools for but just haven't found yet.
hsitz 11y ago
I think Org-mode (in Emacs) does something similar to what you want. Here's link to page with add-on function to add drag'n'drop images to Org files. The web page itself is what was exported from Org, although the export could have as easily been to pdf. There's also link on this page to youtube video illustrating things: http://kitchingroup.cheme.cmu.edu/blog/2015/07/10/Drag-images-and-files-onto-org-mode-and-insert-a-link-to-them/ http://kitchingroup.cheme.cmu.edu/blog/2015/07/10/Drag-image... Org-mode itself uses its own rules for adding Markdown-like formatting, but Org-mode has features that go way beyond Markdown. Here's a fairly simple technical doc with a few images and footnotes: http://kieranhealy.org/files/misc/workflow-apps.pdf http://kieranhealy.org/files/misc/workflow-apps.pdf and here's the org file and images that you were used to author that document and export it to pdf: https://github.com/kjhealy/workflow-paper https://github.com/kjhealy/workflow-paper
- girzel 11y ago
  tl;dr: In your Org mode file, hit C-u C-c C-l, navigate to the image file, hit RET RET, and you're done! Depending on your computer usage habits, it's likely faster than drag-n-drop.
  - hsitz 11y ago
    There are probably a few different ways out there. Here's link to another add-on method that allows for drag and dropping of images directly from a Firefox web page into Org, code handles async downloading of image to local directory: http://thread.gmane.org/gmane.emacs.orgmode/77708 http://thread.gmane.org/gmane.emacs.orgmode/77708 EDIT: the above-linked thread is actually about the beginnings of the 'org-download' extension, now found here: https://github.com/abo-abo/org-download https://github.com/abo-abo/org-download
pjmlp 11y ago
Professional Docbook and DITA based systems like Oxygen XML, Framemaker among others ? https://www.oxygenxml.com/ https://www.oxygenxml.com/ http://www.adobe.com/products/framemaker.html http://www.adobe.com/products/framemaker.html That is how we did it in a few enterprise projects.

tambourine_man 11y ago

In Vim, I usually type <img src="images/… and AutoComplPop[1] sets in, showing all files in that directory. As long as they have a descriptive name, it's probably easier/faster/more reliable than drag and drop. In fact, I actually type img ctrl-E, which expands to the tag above and places cursor at the right place.[2] I know other editor have similar features, so it might be an alternative [1] http://www.vim.org/scripts/script.php?script_id=1879 [2] https://github.com/rstacruz/sparkup

ian97531 11y ago

Try a product called Habitat made by a company called Inkling. https://www.inkling.com/inspiration/ https://www.inkling.com/inspiration/ https://www.inkling.com/habitat/ https://www.inkling.com/habitat/

rubidium 11y ago
looks promising! Definitely attacking the same problem.

rhythmvs 11y ago

That’s exactly the sort of use case we are focussing on and building our automated typesetting service for.¹ You’ll probably also benefit from file inclusions so that you can keep a library of text snippets, with variables, keeping them versioned separately, and which you can then re-use and assemble to form a new, slightly different manual, with the variables automatically populated at typesetting time. Could you be more specific on the problem you’re facing with placing images? Is it that there are like hundreds of them, for which you would want to have created the references (and ![Caption](syntax)) automatically, because typing out the file paths manually is too tedious? That is doable, although it would be more of a drag-and-drop feature to be implemented by a dedicated Markdown editor, or an ST plugin. Or would you like to have more fine-grained control over floats, sizing and placement of the images relative to their place in the text narrative? For which a WYSIWYG interface is indeed more well suited, re: many document author’s gripe with TeX’s figure placement. ¹ http://textus.io/ http://textus.io/

rubidium 11y ago
Glad to hear it. Here's some bullet point thoughts: 1) Workflow needs to be uber-fast and not require saving/naming the images (at least at the user level, the program will of course). Many images are screen shots from SW installs. Workflow goes: Run SW in VM-> screenshot portion of interest -> Copy+Paste into word doc. I never even save the image in that case. The rest of the images are photos of HW. I just want to drag and drop into the document, not rename them all and move them to a same folder with the document. The document/CMS/program should take care of that all for me (like Word does). 2) I do need the text and images to match better and be more WYSIWYG. Location is more important than aesthetics for a guide. It cannot be the abomination that LaTeX is. LaTeX figures are terrible to work with (and that's having published multiple academic papers + PhD thesis in LaTeX). Sizing is less important (that can be [width=x, height=y]). 3) Variables/snippets: Libraries of text snippets and variables is what we do quite a bit of. Right now with a few kludged together macros and custom Word doc properties. Lots of docs go "Run the <SW install name> for <device>" with <> items defined at document level. Sounds like you do this, and it's probably better than how word does :) sorry for dumping on ya, but I'm excited to find people working in this space. It's something I feel like there should be better tools for but just haven't found yet.

hsitz 11y ago

I think Org-mode (in Emacs) does something similar to what you want. Here's link to page with add-on function to add drag'n'drop images to Org files. The web page itself is what was exported from Org, although the export could have as easily been to pdf. There's also link on this page to youtube video illustrating things: http://kitchingroup.cheme.cmu.edu/blog/2015/07/10/Drag-images-and-files-onto-org-mode-and-insert-a-link-to-them/ http://kitchingroup.cheme.cmu.edu/blog/2015/07/10/Drag-image... Org-mode itself uses its own rules for adding Markdown-like formatting, but Org-mode has features that go way beyond Markdown. Here's a fairly simple technical doc with a few images and footnotes: http://kieranhealy.org/files/misc/workflow-apps.pdf http://kieranhealy.org/files/misc/workflow-apps.pdf and here's the org file and images that you were used to author that document and export it to pdf: https://github.com/kjhealy/workflow-paper https://github.com/kjhealy/workflow-paper

girzel 11y ago
tl;dr: In your Org mode file, hit C-u C-c C-l, navigate to the image file, hit RET RET, and you're done! Depending on your computer usage habits, it's likely faster than drag-n-drop.
- hsitz 11y ago
  There are probably a few different ways out there. Here's link to another add-on method that allows for drag and dropping of images directly from a Firefox web page into Org, code handles async downloading of image to local directory: http://thread.gmane.org/gmane.emacs.orgmode/77708 http://thread.gmane.org/gmane.emacs.orgmode/77708 EDIT: the above-linked thread is actually about the beginnings of the 'org-download' extension, now found here: https://github.com/abo-abo/org-download https://github.com/abo-abo/org-download

pjmlp 11y ago

Professional Docbook and DITA based systems like Oxygen XML, Framemaker among others ? https://www.oxygenxml.com/ https://www.oxygenxml.com/ http://www.adobe.com/products/framemaker.html http://www.adobe.com/products/framemaker.html That is how we did it in a few enterprise projects.