Feature proposal: New, Standard Documentation System

[Les Mikesell]

Basil Mohamed Gohar wrote:
> Michael,
>
> What would a new system's advantage over man be?  For example, if a new
> interface to manpages were created, that might eliminate some of the
> initial learning curve some might say manpages present to users.
>
> Actually, I think manpages already solve your 5 points without need
> anything new.  Perhaps a manpage-to-X/HTML solution that allows reading
> them on the fly in a browser could be used to make accessing them
> easier.
>
> So, what this comes down to is creating an easier way to make manpages,
> if what I am suggesting makes sense.
>
> ________________________________________________________________________
>
> Basil Mohamed Gohar
> abu_hurayrah at hidayahonline.org
> www.basilgohar.com
>
>
>
>
> On Wed, 2008-11-26 at 20:28 -0600, Michael Cronenworth wrote:
>   
>> Far too often I find myself looking for non-existent man pages, Google 
>> results, or help menus in GNU/Linux software. What's the problem? There 
>> is no single, reliable, standardized documentation system that is 
>> universally accepted or appreciated. Yes, what I'm about to describe 
>> should obsolete man, info, and all the other dozen "help" documentation 
>> found in all the Fedora packages.
>>
>> Problem case out of the way: Fedora should pioneer a GNU/Linux 
>> documentation system that meets these criteria:
>> 1. Lightweight
>>    The entire system should not demand hundreds of megs of fonts, 
>> images, or other non-reusable requirements. I'm looking at you texlive. 
>> Recommendations: SQLite, ncurses, GTK. Existing toolkits; not new ones.
>> 2. CLI and GUI front-ends
>>    Allow users to be presented to a universal and familiar front-end no 
>> matter where they are. The parts should also be separable so that, for 
>> instance, if there is no X requirement in a said environment, the help 
>> packages should not require QT, GTK, etc.
>> 3. Universal formatting
>>    Obvious criteria, however, application specific formatting should be 
>> allowed as an optional addition after a standard format has been met.
>> 4. Easy to use creation tools
>>    It shouldn't take a programmer background to write help 
>> documentation. Be it WYSIWYG tools or a simple XML-like (hey, or even 
>> XML) language to create documentation pages.
>> 5. Global access
>>   You should be able to access any and all documentation for all 
>> software through a single window, be it X or console, without having to 
>> open the corresponding program.
>>
>> Optional criteria:
>> 1. Platform independence (for use on non-GNU/Linux systems)
>>
>> Feel free to rip me apart. To me, and I'm sure most standard Linux 
>> users, documentation for /any/ piece of software is a nightmare, even if 
>> you are the original author. It should not be that way!
>>     
>
Back in the old days when there weren't so many programs I always liked 
xman in split-screen view so you could see the index of available 
commands in one pane, click on a name, and get the man page in the other 
pane.   However, now that there are thousands of programs with mostly 
meaningless names, the index isn't very useful and the list is too big 
to just browse through everything to see what it does.   If you are 
going to come up with something new, it should provide a way to 
browse/search the short description that 'yum info' would have for a 
package, then view the man/info pages of the associated program(s), 
preferably without having to have the package installed first.  That is, 
you need a way to find which program you want, then the details of how 
to use it.  Man pages only provide the latter (a good thing, because 
you'll need the detail reference often but you'll probably remember the 
overview and not want it to clutter the reference).

-- 
   Les Mikesell
     lesmikesell at gmail.com