[Info-vax] VMS documentation

[Paul Sture]

On 2015-08-04, Simon Clubley <clubley at remove_me.eisner.decus.org-Earth.UFP>
wrote:
> 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. :-)

The HTML output for the LibreOffice spreadsheet is similarly afflicted,
outputting the formatting stuff around each and every cell.

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

I do that too.  On OS X I use two separate programs for this; the system
tries to be too helpful in a "this file is already open, I'll give you
that window instead of opening a new one" way.

I do have a PDF editor but using it to create index entries is pretty
painful and I would definitely look for different tools for anything
as large as a typical VMS manual.

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

But I find Markdown more readable.  For those wondering about the
difference between Markdown and .rst, the former is fine for web pages
but lacks the extras the latter provides for full documents.

I'm not keen on the heavy use of the backtick character `.  Apart from
looking messy, it can be hard to distinguish from a normal single quote,
depending on the font in use.

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

My limited experience says your feeling is right.  It's fine for
producing web pages but PDF generation is over-complicated and does fall
over.  I tried it out earlier this year with the course notes a lecturer
had clearly put a lot of effort into.  Generating the html was simply
a matter of navigating to the right directory and doing "make html".

Doing the same for PDF brought a whole world of pain. I was faced with
the download of several hundred megabytes of TexLive and associated
components and then finally thwarted by a couple of missing fonts.  I
did track those fonts down to a specialist site offering fonts by the
metric tonne but when it advised me to "place these files in an
appropriate directory" I realised I'd just spent far too much time on
a feature which was "nice to have" as opposed to something I needed.

-- 
 If it jams - force it. If it breaks, it needed replacing anyway.