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