Date:   Fri, 22 Jul 2022 20:11:02 +0200
From:   Alejandro Colomar <alx.manpages@...il.com>
To:     "Darrick J. Wong" <djwong@...nel.org>
Cc:     Theodore Ts'o <tytso@....edu>, Jeremy Bongio <bongiojp@...il.com>,
        linux-ext4@...r.kernel.org, linux-man@...r.kernel.org
Subject: Re: [PATCH v2] Add manpage for get/set fsuuid ioctl for ext4
 filesystem.

Hi Darrick,

On 7/22/22 19:46, Darrick J. Wong wrote:
>> Now that you say it, I forgot to document the LIBRARY section in
>> man-pages(7).  There's something about it, but I forgot to add a paragraph
>> describing it in detail.
> 
> That would've helped, since I scanned
> https://man7.org/linux/man-pages/man7/man-pages.7.html
> and didn't see much about what goes in this section...

These changes have been introduced after the last release was made, so 
even if I had documented it, it wouldn't have reached <man7.org>.  I'd 
recommend you to install the man pages from source (`sudo make install`).

> 
>> Regarding the EXAMPLES section, every page in man2 or man3 should have an
>> example program, IMO.  Consider that there are programmers that may find it
>> easier to learn a function by experimenting with a working example of C
>> code, rather than a dense textual description in a language that may not be
>> native to the programmer.
> 
> Frankly I'd rather push people to have example code over documenting
> that standard C library functions require the standard C library. :)

Agreed :)

> 
> That said, I don't always enjoy the textbook examples that have been
> slimmed down for manpages -- I prefer a link to a real implementation
> in (say) the test suite so that I can see code that (one would hope)
> exercises all the functionality exposed through the interface.
> 
> But I guess that's really up to the manpage author to decide.

They're not exclusive.  It's welcome to point to a (stable) link showing 
a more complex example after showing a simple example that fits the page.

> 
>> There are many pages that lack examples, but that's not something I would
>> consider a good thing.
>>
>>>
>>> Some the suggestions you are making don't seem to be adhered to by
>>> the existing man pages, and more text is not always better.
>>
>> The next release of the man-pages is certainly going to be an important one.
>> It may be hated by many, loved by many others.  I hope overall I did a
>> significant improvement in both improving the transmission of information
>> and simplifying maintenance.
> 
> I'm not convinced that having to open *two* manpages just to figure out
> how to call an ioctl is going to simplify maintenance unless the struct
> is shared across more than one manpage, but I've already made that
> point.

Well, I'd say it simplifies maintenance in the case that another page 
adds information about this type: when I receive a patch, I'm not 
grepping all of the pages to see if one already documents a type, to 
decide to move it to a separate page.  It's likely to be forgotten, and 
the documentation about the type duplicated (and they are likely to get 
out of sync).

When I added the type pages, I found many types to be documented 
differently on different pages, needing to copy parts of every page to 
get the full picture, because none of them was complete.  That's 
especially what I'm trying to avoid.

Still, there are many more important types to document in the type 
pages, and if you consider that this one is very unlikely to be shared 
in the long term, then I don't strongly oppose to it being in the same 
page as the ioctl that uses it for now.

> 
> (There isn't any magical way to #include a manpage within another
> manpage, is there?)

Oh, there is.  It's the groff(7) .so request, which is basically the 
same as C's #include directive.  We actually use it a lot in the 
man-pages, to create link pages (a page whose only content is a .so 
request, which basically means its contents are the same as another 
pages').  See for example:

$ cat man2/lstat.2
.so man2/stat.2


Technically, it could be used differently, to include a man page as part 
of another page, but it hasn't been done ever, as it would probably 
complicate how man pages are stored, indexed, and searched in the 
filesystem (there's no </usr/share/man/include/> or </usr/inlucde/man/> 
directory or something like that).

Cheers,

Alex

-- 
Alejandro Colomar
<http://www.alejandro-colomar.es/>

Download attachment "OpenPGP_signature" of type "application/pgp-signature" (834 bytes)

Powered by blists - more mailing lists