On 05/20/2018 07:28 PM, Luc Van Oostenryck wrote: > On Sun, May 20, 2018 at 07:06:58PM -0700, Randy Dunlap wrote: >> On 05/20/2018 06:40 PM, Luc Van Oostenryck wrote: >>> Manpages are a good thing but as an input format it's a >>> nightmare. It would be nice to have a more adapted format >>> for it. >>> >>> So convert the manpage to reST and add to the Makefile what >>> is needed to generate the man page from it. >> >> and this patch doesn't do the Makefile part. :) > > Yes indeed, that was already done in the patch for dev-options. Yep, I noticed that after I sent this comment. >>> NB. This is still an experiment, but it's my intention to >>> make this the source file for the manpage. >>> >>> Signed-off-by: Luc Van Oostenryck <luc.vanoostenryck@xxxxxxxxx> >>> --- >>> >>> Note: This is not yet merged with the main sphinx patches >>> because I don't want the distros to be dependent on >>> sphinx to generate sparse's manpage. >>> I suppose that having the master version in .rst >>> and regenerate the troff/groff version at each change >>> would be an acceptable solution but still I don't like >>> this much. >> >> I would be more concerned about $USER not having sphinx than the >> distros being dependent on it. > > $USER not installing sparse via its distro? Right. > But the problem is the same, anyway. > > Just to be clear, by the 'solution' here above I mean: > - use the .rst as the master version, where all changes are made > - still ship a sparse.1 file so people and distros don't depend on sphinx > - the maintainer must care to regenerate sparse.1 when sparse.rst is > modified. Sure, I got that. But IMO distros will not have a problem with using sphinx. Users might. >>> Changes since v1: >>> * use the '.. option::' directive instead of option lists >>> >>> Documentation/.gitignore | 1 + >>> Documentation/conf.py | 1 + >>> Documentation/dev-options.rst | 4 + >>> Documentation/index.rst | 1 + >>> Documentation/sparse.rst | 462 ++++++++++++++++++++++++++++++++++ >>> 5 files changed, 469 insertions(+) >>> create mode 100644 Documentation/sparse.rst >>> >>> diff --git a/Documentation/sparse.rst b/Documentation/sparse.rst >>> new file mode 100644 >>> index 000000000..92f6a9eeb >>> --- /dev/null >>> +++ b/Documentation/sparse.rst >>> @@ -0,0 +1,462 @@ >>> +.. Sparse manpage by Josh Triplett >>> +.. highlight:: c >>> + >> >> [snip] >> >>> +DEBUG OPTIONS >>> +------------- >>> + >>> +.. option:: -fmem-report >>> + >>> + Report some statistics about memory allocation used by the tool. >>> + >> >> Should we add the -v options here? > > I hesitated myself the other day. > I almost moved this option to dev-options and then I forgot about it. > I really don't have a strong opinion about it. > On one side, most the dev-options (and this -fmem-report) have no > use for the normal sparse users, even the ones that uses it a lot. > On the other side, it's annoying to have two files/manpages for > these options. I think that it makes sense to have two files/manpages and move some of the options from sparse.rst to dev-options.rst. >>> +HOMEPAGE >>> +======== >>> +`http://www.kernel.org/pub/software/devel/sparse/` >> >> I know that this is just a conversion from sparse.1, but that's not much of >> a homepage. The sparse wiki would be better IMO (sparse.wiki.kernel.org). > > Yes, I totally agree. > > -- Luc cheers. -- ~Randy -- To unsubscribe from this list: send the line "unsubscribe linux-sparse" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
