[Info-vax] VMS documentation

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


-- 
Pure Personal Opinion | HoffmanLabs LLC