[Info-vax] VMS documentation

[Dirk Munk]

Paul Sture wrote:
> On 2015-08-04, Dirk Munk <munk at home.nl> wrote:
>> Simon Clubley wrote:
>>> On 2015-07-29, Jan-Erik Soderholm <jan-erik.soderholm at telia.com> wrote:
>>>>
>>>> But of course, do create HTML also if it is not any major
>>>> extra efforts...
>>>
>>> In the GNU world, one of the really nice things about the GNU
>>> documentation tools is that they create HTML, PDF, PS, INFO and text
>>> output all from the same input document.
>>>
>>> Simon.
>>>
>>
>> The source documents should be in a ISO standard format like odt. From
>> those documents you can produce other kind of documents like pdf (also
>> an ISO standard) etc.
>>
>> I'm using LibreOffice for my text documents, it can produce HTML and pdf
>> as well.
>
> Have you looked at the HTML generated by LibreOffice?
>
> Here's a quick example. The following text
>
>      The quick brown fox jumped over the lazy dog.
>      The quick brown fox jumped over the lazy dog.
>
> gives this (wrapped for news)
>
> <p style="margin-bottom: 0cm; line-height: 100%"><font
> color="#000000"><font face="Helvetica, serif"><font size="3"
> style="font-size: 12pt"><span style="letter-spacing: normal"><span
> style="text-decoration: none">The quick brown fox jumped over the lazy
> dog.</span></span></font></font></font></p> <p style="margin-bottom:
> 0cm; line-height: 100%"><font color="#000000"><font face="Helvetica,
> serif"><font size="3" style="font-size: 12pt"><span
> style="letter-spacing: normal"><span style="text-decoration: none">The
> quick brown fox jumped over the lazy
> dog.</span></span></font></font></font></p> <p style="margin-bottom:
> 0cm; line-height: 100%"><br/>
>
>
>> pdf can have a lot of extra functionality, but you need a special
>> program to add that kind of functionality.
>
> IIRC the PDFs contained in the VMS documentation set available 15 or so
> years ago contained clickable indexes, but this functionality got lost
> in subsequent versions.
>
> For the task at hand, something like reStructuredText (aka RST) might be
> more appropriate. It is used for the Python documentation to produce
> HTML and PDF, and can extract documentation from Python modules.
>
> Caveat: good luck installing all the components required without
> a decent package manager to handle all the dependencies. :-)
>
> See the directives section here for a taste of the things RST
> can do:
>
> <http://docutils.sourceforge.net/docs/user/rst/cheatsheet.txt>
>
> and an overview of RST.  Note the emphasis on documentation- processing
> software.  VMS documentation is way too large to do everything by hand.
>
> <https://en.wikipedia.org/wiki/ReStructuredText>
>
> "reStructuredText is a file format for textual data used primarily in
> the Python programming language community for technical documentation.
>
> It is part of the Docutils project of the Python Doc-SIG (Documentation
> Special Interest Group), aimed at creating a set of tools for Python
> similar to Javadoc for Java or POD for Perl. Docutils can extract
> comments and information from Python programs, and format them into
> various forms of program documentation.[1]
>
> In this sense, reStructuredText is a lightweight markup language
> designed to be both (a) processable by documentation-processing software
> such as Docutils, and (b) easily readable by human programmers who are
> reading and writing Python source code."
>

The first thing I wrote was "The source documents should be in a ISO 
standard format like odt." Your examples are far from any ISO standard, 
and I doubt if they are suitable for documents with more complex 
typography or images.

The fact that LibreOffice doesn't produce the best looking HTML at the 
moment, is of no real importance. It can be improved, or you can use 
another tool to produce HTML. As long as you have a good standardized 
type of source document, it is always possible to translate it to 
another type of document.