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@xxxxxxx wrote: > > From: Stéphane Aulery <saulery@xxxxxxx> > > 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@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
