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, 09:24 AM
Patrice Dumas
 
Default Feature proposal: New, Standard Documentation System

On Thu, Nov 27, 2008 at 11:20:23AM +0100, Dominik 'Rathann' Mierzejewski wrote:
>
> +1. Also I'd make it a SHOULD item in review guidelines.

I don't think it should be at all in the guidelines, they are big
enough.

--
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:24 AM
"Aioanei Rares"
 
Default Feature proposal: New, Standard Documentation System

On Thu, Nov 27, 2008 at 12:20 PM, Dominik 'Rathann' Mierzejewski <dominik@greysector.net> wrote:


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



I agree, sometimes Fedora isn't regarded as the best documented distro out there, and
that's bad.
--
Aioanei Rares
schaiba@fedoraproject.org
"China is a big country, inhabited by many Chinese." --Charles de Gaulle


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

On 2008-11-27, 10:06 GMT, Thorsten Leemhuis wrote:
> 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).

+10000 (both on making manpages mandatory and sending them
upstream)

Matěj

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

On 2008-11-27, 04:44 GMT, Basil Mohamed Gohar wrote:
> 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.

In both KDE and Gnome get the "Run application" dialog up and run
man:bash.

Matěj

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

Matej Cepl wrote:

On 2008-11-27, 04:44 GMT, Basil Mohamed Gohar wrote:
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.


In both KDE and Gnome get the "Run application" dialog up and run
man:bash.


'The requested URI "man:///mans" is invalid'

Regards,

Pierre

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

Pierre-Yves wrote:

Matej Cepl wrote:

On 2008-11-27, 04:44 GMT, Basil Mohamed Gohar wrote:
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.


In both KDE and Gnome get the "Run application" dialog up and run
man:bash.


'The requested URI "man:///mans" is invalid'

err "man:///man"


Regards,

Pierre



--
fedora-devel-list mailing list
fedora-devel-list@redhat.com
https://www.redhat.com/mailman/listinfo/fedora-devel-list
 
Old 11-27-2008, 10:37 AM
"Camilo Mesias"
 
Default Feature proposal: New, Standard Documentation System

Hi,

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

I agree with this. Fedora has a lot of good new technology that is let
down by the lack of readily available documentation. Examples include
pm-suspend (no man page but pretty webpages) the greatly understood
selinux (manpages but not enough FAQs or accessible tutorials),
NetworkManager (what does it do in this release?), packagekit, dbus,
etc. Wouldn't it be great if there was a guaranteed way to find
relevant docs for every bit of software in the distro?

I think Michael's mistake is to think that a new tool is the way to
achieve this. Even the most impressive shiny new tool would not make
people create new documentation. What's needed IMO is procedures,
standards and a bit more linking between existing documentation. What
if we had some metrics for documentation, and a league table where
maintainers could see how they are doing wrt. their peers?

-Cam

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

On Thu, 2008-11-27 at 11:06 +0100, 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).
Well, pressurize upstreams or learn to use help2man?

Ralf


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

On Thu, 2008-11-27 at 09:32 +0000, 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).
+1 from me, excellent proposal!

Ralf


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

On 2008-11-27, 10:42 GMT, Pierre-Yves wrote:
>> 'The requested URI "man:///mans" is invalid'
> err "man:///man"

KDE or Gnome? If Gnome (where it works for me) which version of
yelp is installed?

Matěj

--
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 10:00 PM.

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