Red Hat Bugzilla – Bug 808916
[RFE] Introduce more automatism in generating LVM documentation
Last modified: 2016-10-11 19:04:38 EDT
Description of problem:
Acceptable values for "--alloc" isn't documented.
Version-Release number of selected component (if applicable):
Steps to Reproduce:
Provide information about acceptables values (anywhere...)
Did you try "man lvm" ?
Excellent. would it be possbile to quickly document --alloc in those pages. I assume that many people will give-up (or google) when they don't find documentation for an option in the manpage.
May be something like:
> --alloc AllocationPolicy
> The physical extents allocation policy to use.
> see --alloc option in lvm(8) manpage.
If you are interested, I could review the lvm manpages for other options that have the same problem. I could even submit a patch.
It already says:
See lvm for common options.
The only patch I will accept is the one that generates the man pages automatically: anything else is simply unmaintainable. There is already a .h file that contains the commands and args and the normal command man pages should be generated via macros/script based on that file and templates.
> The only patch I will accept is the one that generates the man pages
> automatically: anything else is simply unmaintainable.
If lvm maintainer has problem with maintaining list of options in man page in reliable way, how can we even think that user will find the proper option in man page quickly? :-)
Sorry I couldn't resist but this --alloc question repeats many times and automatic generation of man page will not help users at all. It will just create longer and badly readable man pages...
(I agree with Frank that one line in man page helps here. Specifically for --alloc - it is not obvious it is "common" option here.)
Of course automatic generation absolutely *will* help users as they'll only need to look in one place for the information about the options - which was the whole point of this bugzilla, avoiding the need for the cross-reference. People keep fixing little omissions and yet there are still many missing arguments and inconsistencies in the man pages and going through looking for them all is a total waste of time when that same time could be spent writing a script to generate them and guaranteeing they remain correct now and in the future. Don't anyone waste your time doing that. Write the script.
I might have a look. What would be your prefered and accepted language ? sh? bashism? python?
Something simple and portable that avoids pulling in too many dependencies - so not perl or python.
The descriptions in args.h used as help text should match the prototypes at the top of the man pages.
The "\t[--refresh]\n" bits could be replaced by refresh_ARG which pulls that arg string into the help text too at the right place, and then the list of _ARGs at the end is instead generated from all the ones mentioned in the help text (so coping with cmds that have multiple forms - some args could be mentioned more than once). Probably sorted into alphabetical order in two groups, with the 'interesting' args first followed by the 'boring' common args (like --help).
(A flag in args.h indicating if it's in the 2nd 'common' group.)
[But the change could be done in two pieces, first just doing the man page part using existing _ARGs, then later generating the --help texts from args.h.]
I think it's more complex - actually I plan to commit 168kb patch that updates remaining pieces of man pages to the same style and format like we have in lvcreate. Options should be nicely 'colorized' so they are more readable for users instead of plain text.
So it would have to be made probably more complex in a way, that config options would be stored with 'style' info there (it's probably simpler then writing a tool to do this automatically) - but we then we still have problem the in some case it's worth to do some rearrangement so man pages have better space usage.
Maybe it might be worth to add some #keywords# for some options
and replace them in makefiles as the first step.
But I'm not currently convinced automatic generation of man headers is the best way.
Other thing is - every manpage would get overfilled with so many command line options - which are just taking a lot of space and hide the 'important' bits - i.e. proper info about help,test,debug,verbose... takes several lines with each command and I think we should rather focus on 'extra' options.
So how about to step back a bit for now - and instead of documenting each option in each makefile - replace the line:
"See lvm for common options."
With more clever list of those option which should be looked there?
So a person who tries to find thing knows which options are documented elsewhere ?
For options --debug,--alloc.... see lvm(8).
This reminded me yet another thing we are not documenting as good as we should - we sometimes add a new option into lvm.conf related to some command(s) - but we miss to emphasis this in command's manpage (which might be heavily influenced by such settings). If we would again generate doc for every option in nearly every command (i.e. devices/filter) this would lead to very complicated script generation and most probably unreadable man page - but again I think - we should just add name of variable into the manpage with reference to lvm.conf(5) for detailed description - but I think it's probably worth to got through lvm.conf add some important switches to some man pages.
(It least myself I'm aware of couple missing lines for thinp support in dmeventd).
So while saying this - I'm not against some partial automatic generation of man pages according to some rules - but it should not be probably building whole man-page, just adding some section with reference where to find detailed doc for the option.
Then we could have a rule for inserting 'important' options i.e.
lvremove - we have specific options --force & --noudevsync.
We may have sed replaceable macros:
that would just replace macro with predefined text that gets replaced.
I'm not convinced we could make the same for the command line options - unless we would use something which Dave used for vgcreate - he defined "PHYSICAL DEVICE OPTIONS" - and added reference to pvcreate(8) for them.
Eventually we may put in 'STANDARD OPTIONS' to cover help/test/verbose/debug/quiet/driverload
"METADATA OPTIONS" autobackup/partial/metadata
"TAG OPTIONS" addtag/deltag
And then we also have ENV vars shared (which we miss to reference)
Not really sure how to handle all of this in the best way and avoid to create
much bigger unreadable man pages for all commands....
(changing the subject to better reflect the problem)
(In reply to comment #3)
> automatically: anything else is simply unmaintainable. There is already a
> .h file that contains the commands and args and the normal command man pages
> should be generated via macros/script based on that file and templates.
Just a note: there's also a patchset on review at the moment that makes the lvm.conf settings centralized through its own .h file as well - that could help a bit with making the lvm.conf man page up-to-date as well (bug #820203).
This bug appears to have been reported against 'rawhide' during the Fedora 19 development cycle.
Changing version to '19'.
(As we did not run this process for some time, it could affect also pre-Fedora 19 development
cycle bugs. We are very sorry. It will help us with cleanup during Fedora 19 End Of Life. Thank you.)
More information and reason for this action is here: