[NeXus-committee] Introduction in Docbook format

[Ray Osborn]

I'll hold off for now, but I do think there is a virtue in treating the introduction as a separate entity from the rest of the manual. We want people to feel free to browse through our wiki before diving into the details. At the moment, if you click on the introduction, there is no way back. All the links are internal to the manual. That means that, if people are interested in checking out the FAQ, history, download information, etc, they will be forced to hit the back button. 

Let me stress that the introduction is meant to be just that. It is --not-- documentation. It is advertising. It is designed to give the casual visitor an idea what the format is about. If I were such a user, I would panic the moment I hit the introduction link. It would look as if I was going to have to invest a huge amount of time reading a long manual to understand what it is about.  I would probably decide to go and read Ars Technica instead.

Docbook is not the solution to every problem.

Ray

On Oct 28, 2010, at 2:35 PM, Pete Jemian wrote:

> 
> Ray:
> 
> Please don't do as you suggest.  Give me a chance to respond.
> My attention has been diverted to the HDF5 workshop at DESY.
> 
> Also, please allow me to go back to the listserver logs and retrieve your message.  Just this week, Freddie and I worked out how to get messages to me (the email I was using was not receiving the messages sent).  Now I hear about your comments, I'll look at how to address them.
> 
> Docbook style sheets are possible to tinker with the formatting. Hopefully it will be easy to do, once I learn more about it.
> 
> Pete
> 
> On 10/28/2010 10:58 AM, Ray Osborn wrote:
>> I got no response to my rant last week about how unreadable the new Docbook version of the introduction is - not illegible, just very unpleasant to look at. I see that some of the non-printing characters seem to be okay now, but my complaint still remains.
>> 
>> Unless I hear any objections, I will revert the introduction back to old wiki form, which is much more attractive to read. I will try to update it with any changes in the text in the Docbook version.
>> 
>> I am not suggesting that we abandon Docbook for the main documentation, but style matters. People who are coming to NeXus for the first time will want to see an introduction that is reasonably attractively formatted and pleasant to read. In the long term, does anyone who knows more about Docbook than me know if it is possible to attach stylesheets to the HTML output (and to the printed form), because that might be a longer term solution? Manuals don't have to look boring.
>> 
>> Best regards,
>> Ray
> _______________________________________________
> NeXus-committee mailing list
> NeXus-committee at nexusformat.org
> http://lists.nexusformat.org/mailman/listinfo/nexus-committee

-- 
Ray Osborn
Materials Science Division
Argonne National Laboratory
Argonne, IL 60439, USA
Phone: +1 (630) 252-9011
Email: ROsborn at anl.gov