[NeXus-committee] Formatting the NeXus Reference: Unified nested list

[Joachim Wuttke]

Dear all:

Currently, the NeXus Reference uses two different, overlapping
partial representations to specify the structure and contents
of base classes and application definitions: a tree view, and
member tables.

I am working on utils/nxdl2rst.py to generate a unified nested
list that provides a complete and simple replacement for those
two representations. The attachments (one HTML page, and one
page from the PDF book) show what I have achieved so far.

Unless advised otherwise, I will invest some more time into
this to resolve a couple of minor issues, and then submit
a pull request.

In my view, the proposed new formatting has the following
advantages:

- It removes lots of redundancy, and thereby makes the docs
   clearer, more readable, and much shorter. The PDF book will
   shrink from 390 pages to approx. 290 pages!
- It looks simpler, and therefore helps to make NeXus appear
   simpler.
- It simplifies the scripting machinery behind the documentation.
   The three scripts <category>/nxdlformat.xsl are no longer needed.
   In perspective, we could also replace nxdlxref.xsl and thereby
   take the exotic and unpleasant language XSL completely out of our
   toolchain. All formatting would then be done via Python and Sphinx.
   Maintenance, format polishing, and further development will become
   much easier.

Best regards, Joachim
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.nexusformat.org/pipermail/nexus-committee/attachments/20140820/3c69b952/attachment.html>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: page92.pdf
Type: application/pdf
Size: 26373 bytes
Desc: not available
URL: <http://lists.nexusformat.org/pipermail/nexus-committee/attachments/20140820/3c69b952/attachment.pdf>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: smime.p7s
Type: application/pkcs7-signature
Size: 4916 bytes
Desc: S/MIME Cryptographic Signature
URL: <http://lists.nexusformat.org/pipermail/nexus-committee/attachments/20140820/3c69b952/attachment.p7s>