Feature proposal: New, Standard Documentation System

[Basil Mohamed Gohar]

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!
> 
> Regards,
> Michael
>