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

["Michael Kerrisk (man-pages)" <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>]

Hi Stéphane

On 3 March 2015 at 14:17, Stéphane Aulery <saulery-GANU6spQydw@public.gmane.org> wrote:
> 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.

Thanks for the intro.

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

Okay.

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

Okay.

I have yet to review intro.1, I'm sorry.

Cheers,

Michael

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



-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
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