Subject:
Formats
From:
"J. S. Evans" ####@####.####
Date:
11 Feb 2016 17:54:34 +0000
Message-Id: <56BCCAFA.8030802@email.cz>
Please forgive me for beating a very dead horse, but I've been away for
a few days and I'd like to add something that I hope will be useful.
I am not going to use docbook or linuxdoc. I think they are too time
consuming to learn and the energy required to use them is greater than
benefit.
Here's what I suggest: use whatever you want and stop complaining. Why
do I say that? Am I trolling for a flame war? No. There are some
wonderful apps out there that can convert whatever format that you want
to use to docbook. The primary one is pandoc (http://pandoc.org/).
Using Ubuntu 15.10, the current version of pandoc can work with the
following formats:
Input formats: docbook, docx, epub, haddock, html, json, latex, markdown,
markdown_github, markdown_mmd, markdown_phpextra,
markdown_strict, mediawiki, native, opml, org, rst, t2t,
textile, twiki
Output formats: asciidoc, beamer, context, docbook, docx, dokuwiki,
dzslides,
epub, epub3, fb2, haddock, html, html5, icml, json,
latex, man,
markdown, markdown_github, markdown_mmd, markdown_phpextra,
markdown_strict, mediawiki, native, odt, opendocument, opml,
org, pdf*, plain, revealjs, rst, rtf, s5, slideous, slidy,
texinfo, textile
[*for pdf output, use latex or beamer and -o FILENAME.pdf]
Using this tool, you could literally write your guide in LibreOffice or
MS Word (if you so desire) and convert the docx file to docbook, ready
for upload to git.
The cli command would be:
$ pandoc -f docx -t docbook myHOWTO.docx -o myHOWTO.xml
It's really that simple, though I can't promise you that tweaks won't be
required to get the file perfect. Pandoc isn't the only tool that does
this kind of thing, but it's quite mature and is still being developed.
I think it's a great solution to write how you want without needing to
bicker over formats.
Also, this week I've done a lot of reading this week about lightweight
markup languages: markdown, restructured text, asciidoc, and emacs
org-mode. All of these are very easy to learn and quick to implement
compared to other formats. Personally, I'm going with LyX (it handles
docbook natively) and org-mode since I'm doing more of my work in a vm
without a gui and emacs makes it very easy.
Jason
