FAQ Search Today's Posts Mark Forums Read
» Video Reviews

» Linux Archive

Linux-archive is a website aiming to archive linux email lists and to make them easily accessible for linux users/developers.


» Sponsor

» Partners

» Sponsor

Go Back   Linux Archive > Redhat > Fedora Development

 
 
LinkBack Thread Tools
 
Old 11-27-2008, 01:28 AM
Michael Cronenworth
 
Default Feature proposal: New, Standard Documentation System

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

--
fedora-devel-list mailing list
fedora-devel-list@redhat.com
https://www.redhat.com/mailman/listinfo/fedora-devel-list
 
Old 11-27-2008, 03:44 AM
Basil Mohamed Gohar
 
Default Feature proposal: New, Standard Documentation System

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@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
>

--
fedora-devel-list mailing list
fedora-devel-list@redhat.com
https://www.redhat.com/mailman/listinfo/fedora-devel-list
 
Old 11-27-2008, 04:36 AM
Conrad Meyer
 
Default Feature proposal: New, Standard Documentation System

On Wednesday 26 November 2008 08:44:54 pm 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@hidayahonline.org
> www.basilgohar.com

Konqueror already has one such "manpage-to-HTML" solution when you browse
manpages with "man:foobar" URLs (or something like that, it's been a while
since I've used konqueror).

Regards,
--
Conrad Meyer <konrad@tylerc.org>


--
fedora-devel-list mailing list
fedora-devel-list@redhat.com
https://www.redhat.com/mailman/listinfo/fedora-devel-list
 
Old 11-27-2008, 05:41 AM
Michael Cronenworth
 
Default Feature proposal: New, Standard Documentation System

Conrad Meyer wrote:


Konqueror already has one such "manpage-to-HTML" solution when you browse
manpages with "man:foobar" URLs (or something like that, it's been a while
since I've used konqueror).

Regards,




Before this "manpage-to-HTML" idea goes any further, I'd like to stop
it.



This is not what I have envisioned. An HTML rendering engine is too
beefy. I'm going on previous Fedora requirements of lighter
documentation engines, particularly the release notes in anaconda.



I'll follow up with more detail after the holidays.



--
fedora-devel-list mailing list
fedora-devel-list@redhat.com
https://www.redhat.com/mailman/listinfo/fedora-devel-list
 
Old 11-27-2008, 05:45 AM
"Gergely Buday"
 
Default Feature proposal: New, Standard Documentation System

2008/11/27 Michael Cronenworth <mike@cchtml.com>:
> 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.

Hi Michael,

I think you cannot make each software package maintainer to use your
new tool. And, anyway, most people are fine with man pages. If there
is one...

But it is indeed possible to use modern tools to create textual
documentation. With xmlto you can create man pages (and other formats)
from the same docbook source. Yesterday I started using it and having
found a basic docbook xml source I was able to write a small man page
in two hours.

Now the documentation project is in favor of the Publican system,
which is yet unable to create man pages.

- Gergely

--
fedora-devel-list mailing list
fedora-devel-list@redhat.com
https://www.redhat.com/mailman/listinfo/fedora-devel-list
 
Old 11-27-2008, 05:53 AM
Tom Lane
 
Default Feature proposal: New, Standard Documentation System

Michael Cronenworth <mike@cchtml.com> writes:
> ... Yes, what I'm about to describe
> should obsolete man, info, and all the other dozen "help" documentation
> found in all the Fedora packages.

And you're going to persuade all our thousands of upstream projects
to buy into this and convert their documentation to $whateveritis?

Pardon me for not holding my breath till it happens.

regards, tom lane

--
fedora-devel-list mailing list
fedora-devel-list@redhat.com
https://www.redhat.com/mailman/listinfo/fedora-devel-list
 
Old 11-27-2008, 08:32 AM
"Richard W.M. Jones"
 
Default Feature proposal: New, Standard Documentation System

On Wed, Nov 26, 2008 at 08:28:55PM -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.

Debian forces all programs to come with a man page. If one is
missing, this is considered a bug and packagers have to write one.

http://www.debian.org/doc/debian-policy/ch-docs.html

This would be an excellent idea for Fedora to follow (and we can,
license permitting, use the Debian man pages).

Rich.

--
Richard Jones, Emerging Technologies, Red Hat http://et.redhat.com/~rjones
virt-p2v converts physical machines to virtual machines. Boot with a
live CD or over the network (PXE) and turn machines into Xen guests.
http://et.redhat.com/~rjones/virt-p2v

--
fedora-devel-list mailing list
fedora-devel-list@redhat.com
https://www.redhat.com/mailman/listinfo/fedora-devel-list
 
Old 11-27-2008, 09:06 AM
Thorsten Leemhuis
 
Default Feature proposal: New, Standard Documentation System

On 27.11.2008 10:32, Richard W.M. Jones wrote:

On Wed, Nov 26, 2008 at 08:28:55PM -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.


Debian forces all programs to come with a man page. If one is
missing, this is considered a bug and packagers have to write one.

http://www.debian.org/doc/debian-policy/ch-docs.html

This would be an excellent idea for Fedora to follow (and we can,
license permitting, use the Debian man pages).


My 2 cent: It would be way better for everyone to get those man pages
upstream.


One reason for that: If you add man pages from debian to a fedora
package then you have to recheck every now and then if the man pages are
still up2date. That afaics often tends to be forgotten (I'm guilty
myself here).


CU
knurd

--
fedora-devel-list mailing list
fedora-devel-list@redhat.com
https://www.redhat.com/mailman/listinfo/fedora-devel-list
 
Old 11-27-2008, 09:15 AM
Patrice Dumas
 
Default Feature proposal: New, Standard Documentation System

On Thu, Nov 27, 2008 at 09:32:26AM +0000, Richard W.M. Jones wrote:
>
> Debian forces all programs to come with a man page. If one is
> missing, this is considered a bug and packagers have to write one.
>
> http://www.debian.org/doc/debian-policy/ch-docs.html

I don't think that making a man page should be a guideline in fedora. If
th efedora contributor wants to work a man page with upstream, fine, but
it should be optional.

> This would be an excellent idea for Fedora to follow (and we can,
> license permitting, use the Debian man pages).

If there is a good debian man page and nothing upstream, I think it is
best practice for a packager to use the debian man page. But I don't
think that it needs a guideline, it is fairly obvious that it is right.

Maybe you could add something on
https://fedoraproject.org/wiki/PackageMaintainers/Packaging_Tricks
stating that it is good to work a man page with upstream like debian
does and reusing debian manpage is also worth it.

--
Pat

--
fedora-devel-list mailing list
fedora-devel-list@redhat.com
https://www.redhat.com/mailman/listinfo/fedora-devel-list
 
Old 11-27-2008, 09:20 AM
"Dominik 'Rathann' Mierzejewski"
 
Default Feature proposal: New, Standard Documentation System

On Thursday, 27 November 2008 at 11:06, Thorsten Leemhuis wrote:
> On 27.11.2008 10:32, Richard W.M. Jones wrote:
> >On Wed, Nov 26, 2008 at 08:28:55PM -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.
> >
> >Debian forces all programs to come with a man page. If one is
> >missing, this is considered a bug and packagers have to write one.
> >
> >http://www.debian.org/doc/debian-policy/ch-docs.html
> >
> >This would be an excellent idea for Fedora to follow (and we can,
> >license permitting, use the Debian man pages).
>
> My 2 cent: It would be way better for everyone to get those man pages
> upstream.
>
> One reason for that: If you add man pages from debian to a fedora
> package then you have to recheck every now and then if the man pages are
> still up2date. That afaics often tends to be forgotten (I'm guilty
> myself here).

+1. Also I'd make it a SHOULD item in review guidelines.

Regards,
R.

--
Fedora http://fedoraproject.org/wiki/User:Rathann
RPMFusion http://rpmfusion.org | MPlayer http://mplayerhq.hu
"Faith manages."
-- Delenn to Lennier in Babylon 5:"Confessions and Lamentations"

--
fedora-devel-list mailing list
fedora-devel-list@redhat.com
https://www.redhat.com/mailman/listinfo/fedora-devel-list
 

Thread Tools




All times are GMT. The time now is 05:34 PM.

VBulletin, Copyright ©2000 - 2014, Jelsoft Enterprises Ltd.
Content Relevant URLs by vBSEO ©2007, Crawlability, Inc.
Copyright 2007 - 2008, www.linux-archive.org