[Info-vax] VMS documentation

[Simon Clubley]

On 2015-08-04, Paul Sture <nospam at sture.ch> wrote:
> On 2015-08-04, Dirk Munk <munk at home.nl> wrote:
>>
>> 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/>
>

Not quite as bad as the HTML which Word generates but it's still
pretty bad. :-)

>
>> 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.
>

I'm currently working my way through some manufacturer datasheets which
don't have proper index sections and for the longer ones, I've resorted
to having the document open twice; once for the index pages and once for
reading the rest of the document.

> 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.
>

I've been writing some Python code recently and I can confirm the .rst
stuff is very readable without having to convert it first.

My concern would be that it "feels" a bit fragile for writing full
manuals however.

Simon.

-- 
Simon Clubley, clubley at remove_me.eisner.decus.org-Earth.UFP
Microsoft: Bringing you 1980s technology to a 21st century world