VMS documentation

[Simon Clubley]

HP have just sent me the following message in response to my complaint
a couple of months or so ago about the VMS documentation:

|Hello ,
|
|Thank you for your message to the HP.com corporate
|Feedback to Webmaster. We appreciate the effort to
|notify us of issues with the web site.
|
|Can you please try again, and let us know if you still see a
|problem, it should now be fixed. Sorry for the trouble!
|
|Thank you for reporting the information!
|
|Regards,
|
|Prathiba
|HP webmaster

I've therefore done some checking and the new website is cumbersome
(to put it mildly); it's easier to find things with Google. For example,
searching for "openvms documentation" with Google finds:

http://h30266.www3.hp.com/odl/axpos/opsys/vmsos84/index.html

but I can't find that (or anything similar) as a direct link on:

http://www8.hp.com/us/en/products/servers/openvms/resources.html

Clicking on the documentation links on the latter page takes you to a
search engine (which doesn't appear to work with Javascript disabled).

When you drill down through several levels of the search engine and
eventually get a list of the manuals, they are all only PDF and not
in any apparent logical order. The one I downloaded is downloaded as
"Download.pdf" and not as it's manual name/part number.

What a mess. I've sent the above as a response back to HP as well.

Simon.

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

[Simon Clubley]

On 2015-07-24, Simon Clubley <clubley@remove_me.eisner.decus.org-Earth.UFP> wrote:
> HP have just sent me the following message in response to my complaint
> a couple of months or so ago about the VMS documentation:
>

I've had another response from HP and I've sent them a detailed reply
in response which boils down how awkward it is to have to search for
the manuals instead of having the links to the manuals right there
on the new documentation pages just as they were on the old pages.

HP also said they are moving away from HTML to PDF and I've pointed out
that's a shame as the HTML versions of the VMS manuals made it very easy
to point someone looking for help to the right section of the manual
without them having to download the full manual.

I pointed HP to the ODL documentation page for VMS 8.4 which I found
with Google as an example of how the old pages used to look and how easy
it was to find what you were looking for as a result.

I'll let you know if anything interesting comes out of the feedback.

[Paul Sture]

On 2015-07-28, Simon Clubley <clubley@remove_me.eisner.decus.org-Earth.UFP>
wrote:

> On 2015-07-24, Simon Clubley <clubley@remove_me.eisner.decus.org-Earth.UFP>
> wrote:
>> HP have just sent me the following message in response to my complaint
>> a couple of months or so ago about the VMS documentation:
>>
>
> I've had another response from HP and I've sent them a detailed reply
> in response which boils down how awkward it is to have to search for
> the manuals instead of having the links to the manuals right there
> on the new documentation pages just as they were on the old pages.
>
> HP also said they are moving away from HTML to PDF and I've pointed out
> that's a shame as the HTML versions of the VMS manuals made it very easy
> to point someone looking for help to the right section of the manual
> without them having to download the full manual.
>
> I pointed HP to the ODL documentation page for VMS 8.4 which I found
> with Google as an example of how the old pages used to look and how easy
> it was to find what you were looking for as a result.
>
> I'll let you know if anything interesting comes out of the feedback.

Meanwhile Zipfiles of the complete ODL HTML docsets are available for
download at

<http://h30266.www3.hp.com/ODLIndex.asp>

(who knows how long that will last ...)

Since the table there isn't in date order and is pretty hard to read
I've knocked this up:

<http://openvms.sture.ch/odl_docsets-2015-07-28.html>

--
1972 - IBM begins development on its last tape drive (3480) ever because
of the declining cost of disk drives.

[Craig A. Berry]

Thanks for that. It did make it easier to find the latest ones.

On a related note, the HP Support Center home page currently has this
announcement:

"Important Note: On August 1, 2015 HP Support Center will separate into
two instances, each supporting different product families. User
experience will be retained in both cases, but the "Recent products"
list for signed-in users will be cleared."

Based on how everything has been going so far, mostly likely everyone
who has patch access will lose it temporarily on 1 August until the dust
settles some days or weeks later.

[Phillip Helbig (undress to reply)]

In article <mp8cv0$b1b$1...@dont-email.me>, Simon Clubley

<clubley@remove_me.eisner.decus.org-Earth.UFP> writes:

> HP also said they are moving away from HTML to PDF

Sic transit gloria mundi.

Actually, I liked the BOOKREADER documentation.

[Paul Sture]

On 2015-07-29, Phillip Helbig (undress to reply) <hel...@asclothestro.multivax.de>
wrote:

I have come to prefer PDF but will miss the online HTML.

The online HTML meant that while I could dig out information locally via
PDF or notes I've made, I could then point someone at the relevant
paragraph via a URL. Someone did a good job of putting anchors into the
HTML so that you can supply a link to not just a page but a specific
part of that page e.g. url#paragraph-2

[Jan-Erik Soderholm]

Den 2015-07-29 kl. 11:53, skrev Paul Sture:
> On 2015-07-29, Phillip Helbig (undress to reply) <hel...@asclothestro.multivax.de>
> wrote:
>> In article <mp8cv0$b1b$1...@dont-email.me>, Simon Clubley
>> <clubley@remove_me.eisner.decus.org-Earth.UFP> writes:
>>
>>> HP also said they are moving away from HTML to PDF
>>
>> Sic transit gloria mundi.
>>
>> Actually, I liked the BOOKREADER documentation.
>
> I have come to prefer PDF but will miss the online HTML.
>
> The online HTML meant that while I could dig out information locally via
> PDF or notes I've made, I could then point someone at the relevant
> paragraph via a URL. Someone did a good job of putting anchors into the
> HTML so that you can supply a link to not just a page but a specific
> part of that page e.g. url#paragraph-2
>

It was probably the DEC Document "driver" for HTML that added
the anchors. Anyway, I prefer the PDF files. Download is just
a few seconds today and printing a range of pages is far easier.
It is usualy hard to get clean page breaks from HTML, but then,
HTML was never ment to format "documents" either... :-)

Jan-Erik.

[Bob Gezelter]

Jan-Erik,

Actually, I routinely find both HTML and PDF useful. Since they are both programmatically generated, I see no reason why both should not be provided (particularly since the PDF generator does not seem to generate the internal hyperlinks to individual topics).

When I am researching an issue, I often use the HTML pages for quick reference. If I need to print, I generally print the relevant range of pages from the PDF.

The HTML is also easier to deal with when on a mobile device (e.g., tablet or iPod) since the browsers handle display better than the PDFs at that size and resolution).

It goes without saying that the above is also intended for our friends at VSI, who will be managing the documentation set going forward.

- Bob Gezelter, http://www.rlgsc.com

[Jan-Erik Soderholm]

> ...Since they are both programmatically generated...

At least when DEC Document is (was?) used. Maybe you know
more then me about the current (and future!) tools used. :-)

I notice that most VMS documents are several years old now.
Would it be DEC Document that is used today for updates?

But of course, do create HTML also if it is not any major
extra efforts...

[Simon Clubley]

On 2015-07-29, Jan-Erik Soderholm <jan-erik....@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.

[Jan-Erik Soderholm]

Den 2015-07-29 kl. 17:53, skrev Simon Clubley:
> On 2015-07-29, Jan-Erik Soderholm <jan-erik....@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.
>

What is the tool and what does the source/input look like?

[Simon Clubley]

Texinfo. The home page is http://www.gnu.org/software/texinfo/

The full Texinfo manual is linked from that page in various formats.

[hb]

On 07/29/2015 05:53 PM, Simon Clubley wrote:
> 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.

In the (DEC) Document world ...
$ pipe help/nopromt document release |search sys$pipe version
You can find the Version 3.1 Release Notes in
$ pipe help/nopromt document /text |search sys$pipe Final/wind=(0,30)
Destination Intermediate Final
Keyword Output File Type Output File Type

BOOKREADER DVI_BOOKREADER DECW$BOOK

HELP None. HLP

HTML DVI_HTML HTML

LINE DVI_LINE LINE

LN03 DVI_LN03 LN03

MAIL DVI_LINE TXT

MANPAGE DVI_MNPG 1

PS DVI_PS PS

TERMINAL DVI_LINE TERM

You can then use the output file from the text formatter as an
input file to the device converter.
$

and then there is DOC$ROOT:[GHOSTSCRIPT]GS_AXP.EXE which can be used to
create PDF out of PS.

Agreed, that's technology from the last century:
$ anal/image/sel=link DOC$ROOT:[TOOLS]DOCUMENT_AXP
DOC$ROOT:[TOOLS]DOCUMENT_AXP.EXE;1
12-APR-1999 14:26:40.79
$

[Jan-Erik Soderholm]

Yes, DECdoc and GS is what I have been using.

And nop, current century... :-)

$ anal/image/sel=link DOC$ROOT:[TOOLS]DOCUMENT_AXP
DOC$ROOT:[TOOLS]DOCUMENT_AXP.EXE;1

2-JUL-2001 18:47:50.02
$

$ anal/image/sel=ident DOC$ROOT:[TOOLS]DOCUMENT_AXP
DOC$ROOT:[TOOLS]DOCUMENT_AXP.EXE;1
"DOC V3.3H"
$

[Paul Sture]

On 2015-07-29, Craig A. Berry <craig...@nospam.mac.com> wrote:
> On 7/28/15 3:25 PM, Paul Sture wrote:
>>>
>>> I'll let you know if anything interesting comes out of the feedback.
>>
>> Meanwhile Zipfiles of the complete ODL HTML docsets are available for
>> download at
>>
>> <http://h30266.www3.hp.com/ODLIndex.asp>
>>
>> (who knows how long that will last ...)
>>
>> Since the table there isn't in date order and is pretty hard to read
>> I've knocked this up:
>>
>> <http://openvms.sture.ch/odl_docsets-2015-07-28.html>
>
> Thanks for that. It did make it easier to find the latest ones.

Either I had some finger trouble last night or another one got added
since - AXPDOCAUG15LP.ZIP. I've added that to my list, and also the
sizes in MB, though looking at the current download, these aren't
accurate - the latest IA64 OS zipfile is listed as I64DOCJUN15OS.ZIP
293748 KB on the HP website but Firefox is showing that as 280 MB

293748 / 1024
286.86

A couple of observations.

1. Now that I've done a download or two and had a look, it appears that
the zipfiles contain HTML pointing at PDF files; it's not the HTML
I was expecting. There are however links in there to the online HTML,
e.g.

<http://h30266.www3.hp.com/odl/axpos/opsys/vmsos84/index.html>

2. Don't try unzipping the files on a case sensitive file system and
pointing a browser at it. There's a mix of uppercase URLs with
lowercase files and vice versa which breaks horribly when hosted
on a standard *nix file system.

It works fine on OS X, and I assume, Windows.

> On a related note, the HP Support Center home page currently has this
> announcement:
>
> "Important Note: On August 1, 2015 HP Support Center will separate into
> two instances, each supporting different product families. User
> experience will be retained in both cases, but the "Recent products"
> list for signed-in users will be cleared."
>
> Based on how everything has been going so far, mostly likely everyone
> who has patch access will lose it temporarily on 1 August until the dust
> settles some days or weeks later.

Thanks for the warning.

[Phillip Helbig (undress to reply)]

In article <mpasum$onr$1...@dont-email.me>, Simon Clubley

<clubley@remove_me.eisner.decus.org-Earth.UFP> writes:

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

At least in the past, this was true of VMS documentation as well.

[terry+go...@tmk.com]

On Wednesday, July 29, 2015 at 4:57:01 PM UTC-4, Paul Sture wrote:
> 2. Don't try unzipping the files on a case sensitive file system and
> pointing a browser at it. There's a mix of uppercase URLs with
> lowercase files and vice versa which breaks horribly when hosted
> on a standard *nix file system.

Yup - that's a DOCUMENT-ism. I have a manual which I maintain in DOCUMENT (mostly just to reinforce people's impressions of my oddity 8-) which suffers from that:
https://www.tmk.com/transient/mod-6-generic.pdf / https://www.tmk.com/transient/mod-6-html (hand edited fixups)

Another issue with DOCUMENT is that it uses "Core 35" font names, which not even Adobe uses these days. I ended up editing DOC$ROOT:[TEX.POSTSCRIPT.FONTS]DVC$PS_FONTCONFIG.DAT to fix up the names. And if you don't have the official Adobe fonts, the "best match" substitution will give you some odd placement and kerning artifacts when converting to PDF.

DOCUMENT still works, but license sales / support appears to be defunct (emails asking to purchase an update license and support were unanswered) and you won't find any information about it linked from the TTI home page. Google finds a product page for it on their site which hasn't been updated since 1999. So I don't know that it would be a practical solution for creating new manuals (as opposed to updating existing ones in that format).

[Stephen Hoffman]

On 2015-07-29 22:39:05 +0000, terry+go...@tmk.com said:

> So I don't know that it would be a practical solution for creating new
> manuals (as opposed to updating existing ones in that format).

I've used Document, and have used newer tools. Document is not a
practical solution for new documentation.

There are various limitations and issues with Document, and the tool is
not supported on Itanium.

Use Document to export the source text into another format, and then
import that into a different tool.

I'd use DocBook, TeX or one of the roff tools, in preference. Or one
of the newer WYSIWYG tools.




--
Pure Personal Opinion | HoffmanLabs LLC

[hb]

On 07/29/2015 10:56 PM, Paul Sture wrote:

> 2. Don't try unzipping the files on a case sensitive file system and
> pointing a browser at it. There's a mix of uppercase URLs with
> lowercase files and vice versa which breaks horribly when hosted
> on a standard *nix file system.

I had no problems on Linux when I re-created an Rock Ridge ISO (image
file) with "mksiofs -r" (, created a compressed loop image from that)
and mounted that (as a (c)loop device) with the "check=r" option.

[IanD]

Here's the reply I got...


Dear Customer,


Thanks for your clarification.


From the below links you can see all the open VMS Documentations.

http://h71000.www7.hp.com/doc/spd.html

http://h71000.www7.hp.com/doc/731final/6489/6489pro.html

Please let us know if above links work for you.


Thank you.


Kind Regards

Nithya

Hewlett Packard Company


-----------------------------
I supplied them links that were broken, links to this forum and the HP support forum where it is tabled just how broken things are with specific examples

This is the typical low grade response expected I guess :-(

What concerns me is the constant redirection of the links to the support pages, like a forerunner of where HP is going to push everything. i.e. no support = no documentation? I hope not!

As to the removal of HTML pages for documentation, how can the contents of PDF documents be included on Google searches / web page tolling bots? Seems like a big step backwards having just PDF's IMO

[terry+go...@tmk.com]

On Wednesday, July 29, 2015 at 8:26:46 PM UTC-4, IanD wrote:
> As to the removal of HTML pages for documentation, how can the contents of PDF documents be included on Google searches / web page tolling bots? Seems like a big step backwards having just PDF's IMO

Google has included PDFs in its search data since early 2001. Yahoo! indexes PDFs but I couldn't find a start date.

So the data being in PDF format shouldn't be a barrier to searching on the web. How useful the PDF itself will be to web users depends on a number of things, like whether or not it has "optimize for web viewing" (display before the whole file is downloaded) and whether or not there are hotlinks (both to other locations inside the PDF and to external data) in the PDF.

DOCUMENT's generated HTML looks like mid-90's "web design". And despite the small number of HTML constructs it uses, the pages output are nowhere near standards-compliant (regardless of how old a standard you try). For example, try validating http://www.ttinet.com/doc/App_guide.html at https://validator.w3.org

[li...@openmailbox.org]

On Wed, 29 Jul 2015 22:56:45 +0200
Paul Sture via Info-vax <info...@rbnsn.com> wrote:

> 1. Now that I've done a download or two and had a look, it appears that
> the zipfiles contain HTML pointing at PDF files; it's not the HTML
> I was expecting. There are however links in there to the online HTML,
> e.g.
>
> <http://h30266.www3.hp.com/odl/axpos/opsys/vmsos84/index.html>

That's bad news especially given HP's propensity to move stuff around and
break links. They really need to package everything together so people can
have the doc locally, HTML and PDF.

> 2. Don't try unzipping the files on a case sensitive file system and
> pointing a browser at it. There's a mix of uppercase URLs with
> lowercase files and vice versa which breaks horribly when hosted
> on a standard *nix file system.
>
> It works fine on OS X, and I assume, Windows.

There is a simple config fix for this in Apache. If anybody wants it I'll
post it here, just ask. (I don't remember what it is but I can find it.)

--
Please DO NOT COPY ME on mailing list replies. I read the mailing list.
RSA 4096 fingerprint 7940 3F02 16D3 AFEE F2F8 ACAA 557C 4B36 98E4 4D49

[Simon Clubley]

On 2015-07-30, IanD <iloveo...@gmail.com> wrote:
>
> Here's the reply I got...
>
>
> Dear Customer,
>
>
> Thanks for your clarification.
>
>
> From the below links you can see all the open VMS Documentations.
>
> http://h71000.www7.hp.com/doc/spd.html
>

Interesting. So some of the pages on the old web server are still
available (for now) if you know the direct URL.

As you said, notice how links such as the C compiler manuals just
take you to a search page and even on the odd link with something
useful, such as the V8.4 manuals, notice how the resulting lists are
the same jumbled mess you get when you wade through the search
engine on the new documentation pages.

[Paul Sture]

An excellent idea, thanks.

In both Scientific Linux and openSUSE, mkisofs has been superseded by
genisoimage. The mkisofs command still exists but invokes genisoimage,
ditto for the man page.

From the genisoimage man page:

DESCRIPTION
genisoimage is a pre-mastering program to generate ISO9660/Joliet/HFS
hybrid filesystems.

genisoimage is capable of generating the System Use Sharing Protocol
records (SUSP) specified by the Rock Ridge Interchange Protocol. This
is used to further describe the files in the ISO9660 filesystem to a
Unix host, and provides information such as long filenames, UID/GID,
POSIX permissions, symbolic links, and block and character device
files.

But thanks to your suggestion, I came up with another idea:

zfs create -o casesensitivity=insensitive tank/data/vmsdoc

and I access this from my Mac via Netatalk. So far it's working well :-)

[IanD]

On Thursday, July 30, 2015 at 2:21:12 PM UTC+10, terry+go...@tmk.com wrote:
> On Wednesday, July 29, 2015 at 8:26:46 PM UTC-4, IanD wrote:
> > As to the removal of HTML pages for documentation, how can the contents of PDF documents be included on Google searches / web page tolling bots? Seems like a big step backwards having just PDF's IMO
>
> Google has included PDFs in its search data since early 2001. Yahoo! indexes PDFs but I couldn't find a start date.
>

Thanks for that, I never realised this

[Dirk Munk]

Simon Clubley wrote:
> On 2015-07-29, Jan-Erik Soderholm <jan-erik....@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.

pdf can have a lot of extra functionality, but you need a special
program to add that kind of functionality.

[Paul Sture]

On 2015-08-04, Dirk Munk <mu...@home.nl> wrote:
> Simon Clubley wrote:
>> On 2015-07-29, Jan-Erik Soderholm <jan-erik....@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."

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

[Simon Clubley]

On 2015-08-04, Paul Sture <nos...@sture.ch> wrote:
> On 2015-08-04, Dirk Munk <mu...@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.

[Stephen Hoffman]

On 2015-08-04 10:52:59 +0000, Paul Sture said:

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

Given the effort involved with any documentation port of this scale,
I'd question porting DEC Document SDML into a format intended centrally
for text. Yes, text is centrally important, but the OpenVMS
documentation already contains images, and selective inclusion of audio
or video materials would be appropriate for some documentation.
Formats including eBooks have support for content beyond text. PDF
files can also contain such media, though that's Flash based with all
the problems that brings. But newly-selected documentation tools
should likely support these and potentially other additions, even if
these materials are not in present-day use in the OpenVMS documentation.

For its ability to extract documentation from code, RST looks a bit
like Doxygen <http://www.stack.nl/~dimitri/doxygen/> or Ford
<https://github.com/cmacmackin/ford/>.

Parts of the OpenVMS and product documentation does (did?) import some
material from the OpenVMS source code — for some documentation-related
work, I rewrote and used GNM
<http://www.digiater.nl/openvms/freeware/v80/gnm/> as part of this, and
there's the SDML output available from SDL for generating diagrams —
but the bulk of the OpenVMS documentation build either produces the
documentation itself, or produces files that are then included into the
OpenVMS builds; the help text being familiar examples.

But all that written, a documentation port is no small project, and I'd
assume that VSI will use the existing tools — whatever the specific
hunks are already written in and using — initially.

[Dirk Munk]

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.

[Bob Koehler]

In article <b5i69c-...@news.chingola.ch>, Paul Sture <nos...@sture.ch> writes:
>
> <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/>

So they're trying to be bug-for-bug compatable with MS Office,
including the bloat. I gave up on OpenOffice when they copied too
many MS bugs.

[IanD]

...and here is the latest email I got from HP Re: missing documentation

On 04/08/2015 22:18 PM, HP.com External Mail wrote:
> Dear Customer,
>
>
>
> Thanks for communicating with us.
>
>
>
> We have report this issue to our IT Team. They are restoring the Open VMS documentation site and also working to migrate many other information.
>
>
>
> We will inform you once the site has been updated.
>
>
>
> I'm really sorry for the inconvenience that caused. Request your patience.
>
>
>
> Thank you
>
>
>
> Sincerely,
>
> Prathi
>
> HP.com Webmaster
>
> Hewlett-Packard Company
>
>

I can only take it on face value that things are being put back?

[Paul Sture]

On 2015-08-04, Simon Clubley <clubley@remove_me.eisner.decus.org-Earth.UFP>
wrote:

> On 2015-08-04, Paul Sture <nos...@sture.ch> wrote:
>> On 2015-08-04, Dirk Munk <mu...@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.

[alanfe...@gmail.com]

On Friday, July 24, 2015 at 3:24:51 PM UTC-4, Simon Clubley wrote:
> HP have just sent me the following message in response to my complaint
> a couple of months or so ago about the VMS documentation:
>

[...]

> I've therefore done some checking and the new website is cumbersome
> (to put it mildly); it's easier to find things with Google. For example,

Isn't that typically the case? Or is it just limited to the few websites I've tried it on?

Another advantage of using Google is that if someone sends you a link to an article that has a paywall in front of it, searching for the title of article with Google -- and perhaps adding site:<url of website> -- will often get you in.
[...]
[...]

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

AEF

[Simon Clubley]

On 2015-08-12, alanfe...@gmail.com <alanfe...@gmail.com> wrote:
> On Friday, July 24, 2015 at 3:24:51 PM UTC-4, Simon Clubley wrote:
>> HP have just sent me the following message in response to my complaint
>> a couple of months or so ago about the VMS documentation:
>>
> [...]
>> I've therefore done some checking and the new website is cumbersome
>> (to put it mildly); it's easier to find things with Google. For example,
>
> Isn't that typically the case? Or is it just limited to the few websites I've tried it on?
>

Depends on the website.

For example, Farnell's own search engine is (usually) really good and
provides an overall structure which is totally missing from a Google
search.

OTOH, in a depressing number of cases, I find that even if the same
information is available both via Google and the website itself then
Google tends to give a more readable set of results.

However, you have to be careful that Google isn't pointing you to
an older version of a document instead of the most recent version.
An example for me would be the flash programming specifications
for the PIC32MX range. There are various versions of this document
floating around Microchip's website and Google has pointed me to
older versions of this document in the past.

OTOH, when you are looking for some isolated piece of information (such
as a standalone datasheet) and don't really care where you get it from,
then Google's search comes into it's own.

> Another advantage of using Google is that if someone sends you a
> link to an article that has a paywall in front of it, searching for
> the title of article with Google -- and perhaps adding site:<url of
> website> -- will often get you in.

I find the Google cache to be very useful in a variety of situations.

Simon.

[Simon Clubley]

On 2015-08-13, Simon Clubley <clubley@remove_me.eisner.decus.org-Earth.UFP> wrote:
>
> For example, Farnell's own search engine is (usually) really good and
> provides an overall structure which is totally missing from a Google
> search.
>
> OTOH, in a depressing number of cases, I find that even if the same
> information is available both via Google and the website itself then
> Google tends to give a more readable set of results.
>

Just to clarify, I'm not talking about Farnell in the latter paragraph,
but other websites. Farnell's presentation of information is actually
rather good.