Doc/Manual writing software?

[matt3o]

I need to write a book/manual, I wanted to use a language-agnostic system to be able to switch back and forth between various formats. For example I might want to export to epub, pdf, html, doc, plain text, iBooks Author, and so on.

I was thinking to use markdown with a few markdown extra functionality, from there I could use pandoc to convert between formats.

Problem being I can't find a decent markdown editor for linux. ReText is pretty nice but the preview is terrible and it's very hard to work with it on long documents.

Is LibreOffice the only option here? Exported HTML is terrible and conversion from odt with pandoc a little messy.

[bricomaz]

Exporting nicely between all those formats require a very robust format from the start... DocBook might work for sure, obviously if you don't want to go down the LaTeX pit

I have recently used publican ( https://fedorahosted.org/publican/) which is based on docbook: it's the format used on all Fedora/RedHat documentation. See https://access.redhat.com/documentation/en/ for examples. Once you have written the source file building an html, epub or PDF is as simple as typing

publican build --formats=html,html-desktop,epub --langs=en-US

in the right directory. I us vi for edithing tho

You maybe want to try kile for something more 'visual'.

[Abstractions]

Well, if you use Emacs there are two major modes to look into: https://www.gnu.org/software/emacs-muse/ Muse, and http://jblevins.org/projects/markdown-mode/ Markdown mode. But they have a high barrier of entry(Emacs) so they may not be the best Markdown editors for you.

Maybe http://uberwriter.wolfvollprecht.de/ might be interesting?

[matt3o]

I was exploring latex, but it's quite intimidating... thanks for the suggestions anyway

[klikkyklik]

Perhaps Lyx?

[bricomaz]

I was exploring latex, but it's quite intimidating... thanks for the suggestions anyway

Yes, it can make coffee too. Most of engineering students get to know it for their thesis. Most of their thesis become 'learning LaTeX'

[seaworthy]

They don't have a linux version (offer Mac and Windows version), but Scrivener is deemed to be fantastic for authoring in a robust environment while maintaining diverse exporting options.

https://www.literatureandlatte.com/scrivener.php

[chuckdee]

For help files, I use:

Clarify - http://www.clarify-it.com/
ScreenSteps - http://www.screensteps.com/
HelpScribble - https://www.helpscribble.com/

[matt3o]

scrivener looked promising a pity no linux version

[davkol]

My recommendation is to use the Markdown implementation of pandoc, or AsciiDoc, or even org-mode. Either way, don't worry about editors and previews, because that's the whole point of those formats. (Although GNU Emacs helps a lot, e.g., with making tables in plain text.)

You can do proper typesetting later (or at least automatize most of it on template/makefile level).

[matt3o]

I started working in plain markdown (on a standard text editor), but after 3-4 chapters it becomes very hard to scroll through the document and find a specific section. Consider that I have many images and tables and code.

[Muirium]

And you need a better editor. BBEdit handles markdown headings like it does function calls etc. in source files. Easy to navigate with a pulldown.

Any text editor designed for Markdown should offer this. Otherwise you're essentially stuck in a language it doesn't recognize, so you're on your own.

[davkol]

I started working in plain markdown (on a standard text editor), but after 3-4 chapters it becomes very hard to scroll through the document and find a specific section. Consider that I have many images and tables and code.

Why not use multiple files? Bookmarks on editor level? Labels?

[pr0ximity]

I thought the point of Markdown was that you didn't need an editor, it has a super lightweight syntax.

I second multiple files, concatinate them together manually (not by hand, a shell script would be simple) if the system you're using can't accept multiple files.

I'd like to recommend LaTeX but I'm sure you can get away with Markdown+something.

[matt3o]

I started working in plain markdown (on a standard text editor), but after 3-4 chapters it becomes very hard to scroll through the document and find a specific section. Consider that I have many images and tables and code.

Why not use multiple files? Bookmarks on editor level? Labels?

retext doesn't support "projects" so that wouldn't be possible. Anyway I have a sublime text license I'll look into it.

I thought the point of Markdown was that you didn't need an editor, it has a super lightweight syntax.

I don't care about a "visual" editor, the doc just needs to be easy to navigate.

[scottc]

I was exploring latex, but it's quite intimidating... thanks for the suggestions anyway

Yes, it can make coffee too. Most of engineering students get to know it for their thesis. Most of their thesis become 'learning LaTeX'

I LOVE LaTeX. I used to use it a lot more, but no need right now. I used it for all of my important papers in University. Nothing compares to it for mathematical and formal CS markup.

What I'd probably do here is just write the raw Markdown in Vim (since it's lightweight enough to read most of the time), then bind some shortcut for using PanDoc to turn it into HTML and loading that in a browser for a preview.

I find typing "/# Section Name" to navigate to a section in Vim a pretty nice way to navigate markdown, it seems quite logical to me. But my mind works in strange ways...

[andrewjoy]

GO retro

https://en.wikipedia.org/wiki/Standard_ ... p_Language

[lolpes]

I was exploring latex, but it's quite intimidating... thanks for the suggestions anyway

Yes, it can make coffee too. Most of engineering students get to know it for their thesis. Most of their thesis become 'learning LaTeX'

Yup this! This was what my thesis was all about in the end xD

[matt3o]

all I need is:

- auto TOC
- automatically keep track of chapters
- possibly bookmarks
- bold, italic, quote, code block, headings, lists
- footnotes
- hint and warning box
- code syntax highlight
- easy way to handle attachments
- manual page break
- link between pages would be nice too

I could do everything with markdown (with markdown extra) but I can't find an editor to easily browse through the chapters/sections/files.

Of course I could do with plain txt, but why would I? Machines are meant to ease our work, I don't care about looking cool or uber geek.

[bricomaz]

WARNING: verbose reply. Italians are verbose, you know

all I need is:

- auto TOC
- automatically keep track of chapters
- possibly bookmarks
- bold, italic, quote, code block, headings, lists
- footnotes
- hint and warning box
- code syntax highlight
- easy way to handle attachments
- manual page break
- link between pages would be nice too

I could do everything with markdown (with markdown extra) but I can't find an editor to easily browse through the chapters/sections/files.

Of course I could do with plain txt, but why would I? Machines are meant to ease our work, I don't care about looking cool or uber geek.

WOW. Those look like a lot of requirements to me also if you need to export your manual to various formats too...

May I ask how many pages you think (approx) your manual will be? Are we talking in dozens or hundreds? This might be the main factor, in my opinion. I wouldn't mind learning latex just for, say, a 20 pages booklet... unless you must do it many other times.

auto TOC, bookmarks, keeping track of chapters... you get everything for free with complex environments like LaTeX: of course the learning curve might be steep. https://tobi.oetiker.ch/lshort/lshort.pdf might come in help. Keep in mind that all cross references happens *outside* of the editor, and maybe only after compiling the sources. It's not WYSYWIG so you are forced to think about the structure versus the appearance of your doc. Editing LaTeX in linux is supported by many editors: Texmaker is a nice one specifically made for that. LyX might be good too as it is a semi-wysywig editor but the lyx format is not plain latex.

Anyway: if this is your choice your focus is on the document structure, not the editor.

vi? OK with that. emacs? fine too. eclipse? nedit? gedit? something web based? kile? ... you name it. They will all chew your sources in a way or another.

If you are ok with markup languages (I'm sure you are ) I again advocate publican. It is a stripped down docbook, which is an incarnation of SGML, which is the father of HTML, you know... XML poor cousin publican can cross reference all you want, works with many files (hint: one chapter == one file), easily incorporate pictures (but it's not very table friendly actually), can export in many formats, has a native support for "branding": you can mark your documents with your own graphics, logos, fonts and other peculiar aspects. Learning publican is order of magnitudes easier than latex. editor choice: see the latex reasoning.

Hope this helps.

[klikkyklik]

Lyx - not enough features?

https://www.lyx.org/Features

[matt3o]

WOW. Those look like a lot of requirements to me also if you need to export your manual to various formats too...

there are some options for windows and mac...

anyway I'll look into docbook and the likes. thanks again for the suggestions.

Lyx - not enough features?

https://www.lyx.org/Features

no, that's actually too much. I installed Lyx and all dependencies (500mb... wtf!), it is indeed really good... so far it seems my best option.

[davkol]

Most of that list is just a matter of using pandoc and perhaps having a makefile. Have you read the README for pandoc?

[matt3o]

Most of that list is just a matter of using pandoc and perhaps having a makefile. Have you read the README for pandoc?

I tried pandoc, markdown support is really limited. The source file would need to be something else I guess.

[davkol]

Eh? It's the most powerful implementation out there, by far. It supports TOC, footnotes, definition lists, tables, code listings with syntax highlighting, inline LaTeX formulas, bibliography,…

The only other implementation, that comes close, is MultiMarkdown (which is actually supported by pandoc, although I'm not sure if 100%).

[matt3o]

I gave to it some of the MD files I have and it simply didn't work (MD Extra). Unless the version I have is compiled with a subset of rules. But that besides the point, that doesn't help me during the book writing, unless I set up some sort of bash/whatever script, which I would like to avoid because honestly I could probably code the editor with the feature I need, I was trying to find a ready made solution.

[Chrishas]

Github's Atom is another option:

https://atom.io/

I've only used it myself recently for a small markdown document and it's pretty straightforward.
It has a built-in package manager for extending the functionality.

[matt3o]

just to give davkoi credit, I checked pandoc markdown again and it can be augmented with additional syntax http://pandoc.org/README.html#pandocs-markdown (not everything is enabled by default, that was my initial mistake).

the only thing that is really missing is "admonition". Unfortunately it's a pretty important feature for me, but I understand that you could use a filter for that (http://pandoc.org/scripting.html).

[Muirium]

Admonition, eh. You want your readers to know how cross you are with them?

[pcaro]

I can recommend Sphinx http://www.sphinx-doc.org