Bug 808916

Summary: [RFE] Introduce more automatism in generating LVM documentation
Product: [Community] LVM and device-mapper Reporter: Frank Lin PIAT <fpiat>
Component: lvm2Assignee: LVM and device-mapper development team <lvm-team>
lvm2 sub component: Manual pages and Documentation QA Contact: cluster-qe <cluster-qe>
Status: CLOSED CURRENTRELEASE Docs Contact:
Severity: unspecified    
Priority: unspecified CC: agk, bmarzins, bmr, delete, dwysocha, heinzm, jbrassow, jonathan, lvm-team, msnitzer, prajnoha, teigland, zkabelac
Version: 2.02.166Keywords: FutureFeature
Target Milestone: ---Flags: rule-engine: lvm-technical-solution?
rule-engine: lvm-test-coverage?
Target Release: ---   
Hardware: Unspecified   
OS: Unspecified   
Whiteboard:
Fixed In Version: Doc Type: Enhancement
Doc Text:
Story Points: ---
Clone Of: Environment:
Last Closed: 2019-09-19 17:16:26 UTC Type: ---
Regression: --- Mount Type: ---
Documentation: --- CRM:
Verified Versions: Category: ---
oVirt Team: --- RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: --- Target Upstream Version:
Embargoed:

Description Frank Lin PIAT 2012-04-01 17:17:58 UTC
Description of problem:
  Acceptable values for "--alloc" isn't documented.

Version-Release number of selected component (if applicable):
  2.02.88

How reproducible:
  n.a

Steps to Reproduce:
1.
2.
3.
  
Actual results:
n.a

Expected results:
  Provide information about acceptables values (anywhere...)

Additional info:

Comment 1 Milan Broz 2012-04-01 18:23:37 UTC
Did you try "man lvm" ?

Comment 2 Frank Lin PIAT 2012-04-03 06:17:47 UTC
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.

Comment 3 Alasdair Kergon 2012-04-03 06:51:48 UTC
It already says:

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

Comment 4 Milan Broz 2012-04-03 07:54:33 UTC
> 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.)

Comment 5 Alasdair Kergon 2012-04-03 23:17:46 UTC
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.

Comment 6 Frank Lin PIAT 2012-04-04 06:31:26 UTC
I might have a look. What would be your prefered and accepted language ? sh? bashism? python?

Comment 7 Alasdair Kergon 2012-04-04 08:19:43 UTC
Something simple and portable that avoids pulling in too many dependencies - so not perl or python.

m4 perhaps?

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

Comment 8 Zdenek Kabelac 2012-04-04 08:45:14 UTC
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 ?

 i.e.

 For options --debug,--alloc....   see lvm(8).

Comment 9 Zdenek Kabelac 2012-04-04 15:32:42 UTC
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:

#MANOPT_FORCE_REMOVE#
#MANOPT_NOUDEVSYNC#

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

Comment 10 Peter Rajnoha 2012-09-12 09:12:26 UTC
(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).

Comment 11 Fedora End Of Life 2013-04-03 16:00:10 UTC
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:
https://fedoraproject.org/wiki/BugZappers/HouseKeeping/Fedora19

Comment 12 David Teigland 2019-09-19 17:16:26 UTC
Fixed when lvm adopted command definitions and generated help/man output.