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 12-01-2008, 12:56 PM
Les Mikesell
 
Default Feature proposal: New, Standard Documentation System

Matej Cepl wrote:

On 2008-12-01, 01:45 GMT, Michael Cronenworth wrote:
Man pages, while informative, are limited. If examples or
detailed information are required then you're back to Google
searching.


Yes, there are many manpages which are pretty bad. But expanding
content won't happen by switching to different format, but fixing
each manpage. Yes, one at the time.


Adding a few examples won't hurt, but man pages are not the place for
conceptual fluff. We need some other format to hold an overview of why
you should use each program and how various program can be combined to
accomplish different results. Man pages should just contain a reference
for that program's use, because you won't look there until you already
know why you want to run it.


--
Les Mikesell
lesmikesell@gmail.com


--
fedora-devel-list mailing list
fedora-devel-list@redhat.com
https://www.redhat.com/mailman/listinfo/fedora-devel-list
 
Old 12-01-2008, 01:01 PM
"Camilo Mesias"
 
Default Feature proposal: New, Standard Documentation System

2008/12/1 Les Mikesell <lesmikesell@gmail.com>:
> Adding a few examples won't hurt, but man pages are not the place for
> conceptual fluff. We need some other format to hold an overview of why you
> should use each program and how various program can be combined to
> accomplish different results. Man pages should just contain a reference for
> that program's use, because you won't look there until you already know why
> you want to run it.

Don't forget you can have manpages for conceptual fluff (try man
selinux / which selinux), and you can find out what command you need
to do using 'apropos'. Example: apropos security

The man system really has been round the block a few times...

-Cam

--
fedora-devel-list mailing list
fedora-devel-list@redhat.com
https://www.redhat.com/mailman/listinfo/fedora-devel-list
 
Old 12-01-2008, 01:05 PM
Les Mikesell
 
Default Feature proposal: New, Standard Documentation System

Alphonse Van Assche wrote:

Michael Cronenworth a écrit :

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


6. a common way to find documentation about a given package. Here is
what I do when I need to read docs on a given package.


1. rpm -ql pgkname
if there is a man page and/or README and/or .html and/or ... - done!
2. yum list pkgname*
if there is sub-package named pkgname-doc - done!
3. rpm -qi pgkname
if the URL tag point to upstream web site - open firefox find the
documentation page - done!
4. fedora-cvs pkgname - hoping that I know the language used and that
the code is nicely documented ;-) - done!

5. ??

I thing that we can do something to optimize the search of documentation
of a given package. To be honest I don't have any idea on the best way
to do that - but I'm sure that we can do something better.


Yes, that approach is horrible and your example starts from the point of
already knowing the package name. We need a reasonable way for someone
to find a new package (or any package they don't know about) that would
perform some operation useful to them even if they don't have it
installed yet. Google, of course, knows everything, but even with a
carefully crafted search will usually return a lot of irrelevant results
related to other OS's or different version numbers.


--
Les Mikesell
lesmikesell@gmail.com

--
fedora-devel-list mailing list
fedora-devel-list@redhat.com
https://www.redhat.com/mailman/listinfo/fedora-devel-list
 
Old 12-01-2008, 03:29 PM
"Gergely Buday"
 
Default Feature proposal: New, Standard Documentation System

Basil Mohamed Gohar

> If someone could setup a SIG for man page conversion or just leverage
> the documentation team and make a focus on teaching how to do man pages,
> I could see this bits of this task being chipped away significantly on
> the road to F11. I know that I'm definitely leaning towards the idea of
> writing one or two man pages, because I've run into the missing-man-page
> problem too often.

I do not have the time this week being ill but am willing to do this.
Could anyone please point me to a corner of Fedora wiki that would be
suitable for such a page? OK I can create a page on my own with a name
of my like, but where to put links?

- Gergely

--
fedora-devel-list mailing list
fedora-devel-list@redhat.com
https://www.redhat.com/mailman/listinfo/fedora-devel-list
 
Old 12-01-2008, 03:55 PM
Les Mikesell
 
Default Feature proposal: New, Standard Documentation System

Camilo Mesias wrote:

2008/12/1 Les Mikesell <lesmikesell@gmail.com>:

Adding a few examples won't hurt, but man pages are not the place for
conceptual fluff. We need some other format to hold an overview of why you
should use each program and how various program can be combined to
accomplish different results. Man pages should just contain a reference for
that program's use, because you won't look there until you already know why
you want to run it.


Don't forget you can have manpages for conceptual fluff (try man
selinux / which selinux), and you can find out what command you need
to do using 'apropos'. Example: apropos security


But I would never have thought to use 'man' on a meta-package name, so
that's only useful after some user training (or the tutorial where such
information really belongs anyway). And 'apropos security' should
probably list every program with any security related aspect. That is,
if it worked like it should, there would be too many results to be useful.



The man system really has been round the block a few times...


And it only really worked when it was accompanied by a separate tutorial
and overview and the list of programs was small enough to browse with
xman or search with 'man -k'. The pages themselves are generally fine
once you get to the point of wanting refernce details, but now that
there are many thousands of choices you need to know where to start.


--
Les Mikesell
lesmikesell@gmail.com

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

On Mon, Dec 01, 2008 at 12:53:34PM +0200, Basil Mohamed Gohar wrote:
>
> Should I present this idea to the docs project, pending the agreement of
> most, if not all, those involved in this discussion? I'm mulling the
> idea of even heading it, if no one else is more appropriate for the
> task...

That is definitely the right attitude, thanks. "Better man pages" was
on the list of Red Hat's various technical writing teams since
... 1999? The problem is resources -- it is a huge task for a small
group of people to wade through.

As Rahul pointed out, mitwi is an example of working to make man pages
accessible from a documentation site without manual intervention. It
came from a goal of putting a simpler (wiki) interface in front of man
pages, with automagic conversion behind the scenes.

But even with the easiest tools we can muster, it is still a giant cat
herding effort to get packagers behind man page improvements. What is
needed is that can-do attitude, followed by the actual doing, of
course.

- Karsten
--
Karsten 'quaid' Wade, Community Gardener
http://quaid.fedorapeople.org
AD0E0C41
--
fedora-devel-list mailing list
fedora-devel-list@redhat.com
https://www.redhat.com/mailman/listinfo/fedora-devel-list
 
Old 12-09-2008, 10:20 AM
Basil Mohamed Gohar
 
Default Feature proposal: New, Standard Documentation System

On Tue, 2008-12-09 at 02:42 -0800, Karsten Wade wrote:
> On Mon, Dec 01, 2008 at 12:53:34PM +0200, Basil Mohamed Gohar wrote:
> >
> > Should I present this idea to the docs project, pending the agreement of
> > most, if not all, those involved in this discussion? I'm mulling the
> > idea of even heading it, if no one else is more appropriate for the
> > task...
>
> That is definitely the right attitude, thanks. "Better man pages" was
> on the list of Red Hat's various technical writing teams since
> ... 1999? The problem is resources -- it is a huge task for a small
> group of people to wade through.
>
> As Rahul pointed out, mitwi is an example of working to make man pages
> accessible from a documentation site without manual intervention. It
> came from a goal of putting a simpler (wiki) interface in front of man
> pages, with automagic conversion behind the scenes.
>
> But even with the easiest tools we can muster, it is still a giant cat
> herding effort to get packagers behind man page improvements. What is
> needed is that can-do attitude, followed by the actual doing, of
> course.
>
> - Karsten
Karsten,

So, do I need to take any formal steps to move forward?

This would be my most significant involvement with Fedora if I do take
it up to some degree. Not being a significant developer (aside from
PHP), this is about the best way I can contribute back to the project
right now.

My idea is that at least I can kick-off a sustainable system that could
work to fill-in the missing man pages and establish a culture within the
already existing upstream-positive culture of Fedora to contribute back
man pages as well as general patches & code. Having a wiki-like or
other system in place to work on man pages would be a great way for
upstream to verify & even contribute back to their own pages (think
something like Launchpad, but focused just on documentation).

Okay, so back to my main point: is there an official step I have to take
to start an initiative like this?

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

2008/11/27 Todd Zullinger <tmz@pobox.com>:
> Trond Danielsen wrote:
>> Last time I checked both man and info pages are available though the
>> gnome yelp browser. That already provide a convenient and searchable
>> interface for both experienced and inexperienced users.
>
> Check again.
>
> This seems to be broken on F10 at least, and possibly F9 as well -- it
> has been a while since I checked on F9. Matěj filed this bug earlier
> today: https://bugzilla.redhat.com/show_bug.cgi?id=473257

That is only a problem if you try to launch the yelp browser from the
command launcher. If you start it from the command line or by clicking
on the system menu browsing man pages work just fine.

However, the point I was trying to make is that a unified interface
that provide access to both info pages, man pages and gnome help files
(XML).

--
Trond Danielsen

--
fedora-devel-list mailing list
fedora-devel-list@redhat.com
https://www.redhat.com/mailman/listinfo/fedora-devel-list
 
Old 12-09-2008, 07:29 PM
Karsten Wade
 
Default Feature proposal: New, Standard Documentation System

On Tue, Dec 09, 2008 at 01:20:18PM +0200, Basil Mohamed Gohar wrote:
>
> Okay, so back to my main point: is there an official step I have to take
> to start an initiative like this?

You know Fedora, we pride ourselves on our "be bold and do it"
spirit. Well, unless we are complaining about the bureaucracy.

All I ask is you to send a self-intro[1] embedded in a discussion opener
to fedora-docs-list; obviously join the list. We want to scope out
solution(s) and culture change ideas there, then bring a well formed
proposal/plan back to groups such as f-devel-l.

Within that planning process, we'll likely discover early that we need
some resourcs such as a publictest server instance to start
prototyping. We can sort those requests out as needed.

Alternately, and we can consider this ... do we gain by keeping the
discussion on fedora-devel-list? It feels to me that we've squeezed
the juice out of the ideas here so far, and it's time for a smaller
group (sub-project such as Docs) to take it aside and bring back
something more to squeeze. But that is just a feeling, I'm open to
other ideas.

- Karsten
[1] That's the "how to join Docs" step that really matters:

https://fedoraproject.org/wiki/DocsProject/Join#Signing_Up
--
Karsten 'quaid' Wade, Community Gardener
http://quaid.fedorapeople.org
AD0E0C41
--
fedora-devel-list mailing list
fedora-devel-list@redhat.com
https://www.redhat.com/mailman/listinfo/fedora-devel-list
 
Old 12-10-2008, 04:23 PM
Basil Mohamed Gohar
 
Default Feature proposal: New, Standard Documentation System

On Tue, 2008-12-09 at 12:29 -0800, Karsten Wade wrote:
> You know Fedora, we pride ourselves on our "be bold and do it"
> spirit. Well, unless we are complaining about the bureaucracy.
>
> All I ask is you to send a self-intro[1] embedded in a discussion opener
> to fedora-docs-list; obviously join the list. We want to scope out
> solution(s) and culture change ideas there, then bring a well formed
> proposal/plan back to groups such as f-devel-l.
>
> Within that planning process, we'll likely discover early that we need
> some resourcs such as a publictest server instance to start
> prototyping. We can sort those requests out as needed.
>
> Alternately, and we can consider this ... do we gain by keeping the
> discussion on fedora-devel-list? It feels to me that we've squeezed
> the juice out of the ideas here so far, and it's time for a smaller
> group (sub-project such as Docs) to take it aside and bring back
> something more to squeeze. But that is just a feeling, I'm open to
> other ideas.
>
> - Karsten
> [1] That's the "how to join Docs" step that really matters:
>
> https://fedoraproject.org/wiki/DocsProject/Join#Signing_Up
> --
> fedora-devel-list mailing list
> fedora-devel-list@redhat.com
> https://www.redhat.com/mailman/listinfo/fedora-devel-list

Thanks Karsten, that's what I needed. I think I'm already on the Docs
list, but I'll do the introduction and post some of the most succulent
ideas from this thread (at least, as I see them) there. And I agree
with moving this to the docs list, and if we need devel input, then we
can always cross-post when needed, rather than saturate devel with
tangential issues.

--
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 03:59 PM.

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