[NeXus-committee] comments on PDF manual

[Pete Jemian]

Joachim:

Thanks for the feedback.  This is definitely a difference in what is 
provided in Sphinx to render HTML and PDF versions of the same document. 
  I have avoided using Sphinx commands in the documentation for "if HTML 
then do this" and "if PDF, then do this".  As we switched from DocBook 
to Sphinx we realized that the manual content would get quite long, 
likely that only a few would wish to print it.  Thus, the preference has 
been on the HTML rendering.

If anyone has suggestions to improve the appearance (and ordering of 
parts) in the PDF without affecting the HTML, please offer them.  For 
example, clone the git repo, make changes, and submit a pull request.

I'll enter your comments as a GitHub issue.
https://github.com/nexusformat/definitions/issues/283

People have complained about how long the manual is and how difficult it 
is to see the basic structure.  This translates into their perception 
that NeXus is too difficult to learn.  The table of contents was kept 
brief for this reason while attempting to supplement that brevity with a 
rich index.  I'd prefer to maintain this approach.  Short Table of 
Contents, long index.  Your comments about placement of NX... in the 
index have an easy solution.  Move the depth as you suggest yet add a 
"refer to" under class definitions.

Thanks,
    Pete

On 7/8/2014 8:24 AM, Joachim Wuttke wrote:
> I am reading the compound PDF manual, release 3.1 of 2014-06-10.
>
> I printed and bound the 360 pages, so that it feels like a serious
> book. The first thing I then noticed is the absence of proper
> front matter: copyright notice, document license, authors, year,
> contact address with invitation to send feedback.
>
> Lacking such information, I am sending my feedback to this list.
>
> In Sect. 2.3.1 "NeXus Class Specifications", unnumbered
> subsubsubsection "Overview of NeXus classes", first paragraph says:
> "... is described in two basic ways: First, ..., then ..., then ..."
> This makes three. Anyway, for easy readability, "first" should be
> followed by "second", not by "then".
>
> Two pages further on, there is a subsubsubsection "NeXus Class
> Specifications", which repeats the header of the subsubsection.
> It is immediately followed by the subsubsubsubsection header
> "Base Clase Definitions". Which means that the core of the manual,
> the definitions of the individual classes, resides in
> subsubsubsubsubsections. I suggest to restructure this so
> that the individual definitions are promoted to subsubsection
> level, and listed in the table of contents.
>
> Looking for a class definition in the index, it took me quite
> a while to find it not under "NX..." but under "class definition".
> I suggest to give up the two-level hierarchy of the index in
> favor of a strictly alphabetical order. An index should primarily
> support quick search. To expose the systematics of the manual,
> it would be more appropriate to make the table of contents
> more exhaustive, going down at least to subsubsection level.
>
> Best - Joachim
>
>
>
> _______________________________________________
> NeXus-committee mailing list
> NeXus-committee at nexusformat.org
> http://lists.nexusformat.org/mailman/listinfo/nexus-committee
>