Re: man5/filesystems.5: updated list and descriptions of supported filesystems

["Stéphane Aulery" <saulery-GANU6spQydw@public.gmane.org>]

Hello Michael,

A little introduction is necessary I suppose.

I am a French developer (but not C/C++) and I use Debian at home. I regularly
give small contributions to the distribution and I look at the man pages by
now.

My plan was to fix as many bugs as possible about the manpages and
manpages-dev Debian packages [1]. I also think of missing IOCTL for linux
framebuffer because I contribute to a program that uses them.

I wonder about the right way to improve the overall quality of the man
pages, not just to provide factual information on such and such a
program, but also to guide the reader toward a better understanding of
the system. So my patches on intro.1 and filesystems.5.

[1] https://bugs.debian.org/cgi-bin/pkgreport.cgi?repeatmerged=no&src=manpages

Le mardi 03 mars 2015 à 01:14:25, Michael Kerrisk (man-pages) a écrit :
> 
> On 03/03/2015 09:58 AM, saulery-GANU6spQydw@public.gmane.org wrote:
> > From: Stéphane Aulery <saulery-GANU6spQydw@public.gmane.org>
> 
> I appreciate the work your doing on man pages, but it would 
> be helpful if you could do the following:
> 
> 1. When making sizable updates to existing pages, give
>    me a little warning, telling me of the planned changes;
>    then I could make suggestions such as I do in the next
>    point before you embark on the work.

Ok, I will.

> 2, Patches like this are way too "busy" for me to easily 
>    deal with. You are doing multiple things in one patch:
> 
>        + Placing the existing entries in alphabetical order
>        + Adding very many new filesystems in a single patch.
> 
>    All of the above seems very fine to me, but... at the
>    very least, this should be a patch that does those two
>    steps separately, in the above order. Then I can more easily
>    distinguish what's being moved around versus what's being 
>    added.
> 
>    I think it would also be better to split the additions 
>    into logically related pieces. In the most extreme case, one
>    patch per filesystem, but maybe it can be done more 
>    efficiently than that.

I can send interdependent patches then.

> 3. Read man-pages(7) quite closely. One of the things it notes 
>    is that new sentences should start on new source lines
>    (and when breaking long sentences, breaking after punctuation
>    [.,;:] is preferred).

I usually wraps text with par utility, it's nicer. I'll change.

> Could you do the following:
> 
> a) Submit a patch that places the existing entries into alphabetical
>    order, making if necessary rewordings to the text to reflect
>    any order changes. (I'm not sure whether any such rewordings are 
>    needed)

I cook it.

> b) Send me a *list* of the filesystems you propose to add, 
>    possibly with suggestions on how those FSes could be added 
>    in patches that add multiple related FSes.

And that, too.

I want to add all supported file systems (or formerly supported) by the
Linux kernel and the following information:
- id
- Full name
- Description (if needed)
- Version of apparition
- Status: alpha, stable, experimental, etc.
- OS and date of origin
- Operation (read / write)
- The type of use (disk, floppy, distributed, etc.)
- Variants
- Some important information if necessary

> c) Then we can see about the best way of adding those new FSes...

The reader should be able to determine if X or Y file system is
supported and possibly lead to a specific man page or the kernel
documentation for difficult cases.  I do not know whether to make a
table, categorize?

> Does the above make sense?

Yes, certainly.

Thank you for your long development.

Regards,

-- 
Stéphane Aulery
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html