[Info-vax] DEC/TTI Document (was: Re: directories other than SYS* on the system disk)

[Paul Sture]

On 2015-01-02, Scott Dorsey <kludge at panix.com> wrote:
> Stephen Hoffman  <seaohveh at hoffmanlabs.invalid> wrote:
>>
>>Probably time to look around again, and see if there's a reasonable 
>>replacement for a text-based formatting tool, and that I can migrate 
>>into.  DocBook and the roffs were seemingly the available options, back 
>>when I last looked.  Those tools worked, but weren't as easy to install 
>>or use or target as I'd hoped.   It's likely that things here have 
>>improved since that last looked, though.  The new stuff I'm working 
>>with and writing already uses other documentation tools, and the last 
>>(big) hunk of SDML around is the old FAQ.
>
> I don't suppose LaTeX would make you happy?

A little over a year ago I had a bash with the Python documentation
toolchain, Sphinx (not to be confused with the search engine of the
same name).  Sphinx uses LaTex as an intermediate stage in the
production of PDF files.

<http://sphinx-doc.org/>

As I recall, the complete process was similar to Hoff's experience,
"not as easy to install or use or target as I'd hoped".  For example
somewhere in there I came across a tool which the author had clearly
once been proud of (and worked well as far as I could see), but
had abandoned.

One conclusion I came to from that exercise was that although
Markdown seemed simpler to learn than Restructered Text (RST),
Markdown was suitable for short documents such as web pages
but reStructuredText (to use its proper moniker) is more
suitable for manuals and books.

-- 
"Machines take me by surprise with great frequency." - Alan Turing