Subject:
Re: Formats
From:
David Lawyer ####@####.####
Date:
24 Feb 2016 04:02:43 +0000
Message-Id: <20160224040340.GG19608@daveslinux>
On Thu, Feb 11, 2016 at 06:55:06PM +0100, J. S. Evans wrote:
> 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.
I found that using linuxdoc to create a table of contents (TOC) was a lot
faster than doing it manually, counting the short time it took to figure
out how to use linuxdoc (starting with a linuxdoc template). Linuxdoc is
about as easy as a wiki markup (without templates)
>
> 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:
I'll have to see it to believe it. The automatic conversions at LDP from
linuxdoc to docbook contained a lot of wrong format. If pandoc can do
what it claims, we can covert docbook to mediawiki. But jdd said that it
didn't come out right when he tried to convert docbook to a wiki (but LDP
doesn't use mediawiki). If pandoc works well, LDP could convert
everything to mediawiki provided it's easy to edit/test mediawiki. What I
don't know is: how easy is it to convert mediawiki to get stand-alone
html. The conversions done at wikipedia (using mediawiki) seem to not not
result in a stand-alone html doc, but need to have access to data on
wikipedia sites when displaying html on your screen. There is also the
complexity of having a lot a special templates and add-ons. (Continued near
end of this email)
>
> 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
>
Where is linuxdoc and plaintext in this list? But as I recall one can
convert asciidoc to linuxdoc.
> 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.
I haven't looked into it but there is a wiki called DokuWiki which is
open-source, designed for documentation. I'm ignorant as to whether or not
it's easy to edit wiki docs offline and check to see if they display
correctly in html.
When mentioning all feasible markup formats (including plain text which
needs to have at least and author and date) in LAG there needs to be a
link to other pages briefly describing their markup (with examples), etc
and hopefully containing enough info to get someone started writing.
Also, what about mentioning the how-to generator at :
Linkname: The LDP HOWTO Generator
URL: http://www.nyx.net/~sgjoen/The_LDP_HOWTO_Generator.html
Does this work OK now? It uses a template with instructions in the
template to create linuxdoc.
The post by jdd on this format thread is correct. There is just no way to
create a Docbook file from say an html format. html has no section heads
unless one has used the size of font to imply a section head in html.
html doesn't require an author or date, etc.
Should LDP accept all formats? No. First of all, a doc needs to contain the
authors name, email (perhaps scrambled), and date of revision and a
perhaps a note as to whether or not the revision is minor. There should
be preferred formats and a few formats that we suggest for authors who
have never used a format (other that plain text such as in email).
that doesn't convert to others
David Lawyer
