Message: previous - next
Month: February 2014

Re: [trinity-devel] Re: New package check list

From: "David C. Rankin" <drankinatty@...>
Date: Sun, 23 Feb 2014 04:28:46 -0600
On 02/22/2014 05:37 PM, Darrell wrote:
> Interesting picture. The fact that the alleged help file opens means little.
> So now add another item to the check list:
> * The app supports a standard help handbook docbook format (not a
> I-am-a-lazy-ass-developer html file).
> These lazy-ass html files do not satisfy any of the help handbook criteria.
> There is no docbook file.
> krename and kdbg fall into this same category.
> Somebody with some serious scripting savvy could help by creating a
> conversion script. I have search the web and nobody has anything of quality
> to convert html to docbook.

There are some distinct advantages to html over docbook, especially for any
large help files. I much prefer being able to scroll up/down and quickly find
the information I need rather than trying to click Next/Back/Up/Home trying to
hop around getting from point A to B in docbook.

Now docbook indexing is an advantage over HTML, but HTML provides a distinct
advantage in usability.

Testing kxmleditor, I select Help from the Help menu and a very clean and
complete help document appeared. The average user doesn't care what format the
underlying information is contained in, they just want good and useful help when
they press [Help].

As for as a conversion script goes, it shouldn't be that hard to develop. I'll
look at it when I get systemd done. I say the docbook standards in the admin or
one of the other guides in the past day or so.

Honestly, providing both wouldn't be a bad idea, especially for the longer
manuals if that is possible. I don't know if they conflict with each other, but
I found myself earlier using meinproc to change the administrative-guide back to
html for just these reasons. It is almost impossible to hop back and forth
effectively in docbook, but it is simple to grab the scrollbar on the window and
move from the top to bottom, or any point in between, with the html file.

I think for all all core-tde modules, docbook is a 'must have', but for all the
non-core modules it becomes much more of a 'nice to have' as long as good help
is available when you press F1.

David C. Rankin, J.D.,P.E.