On Fri, 2017-02-17 at 09:32 -0800, Ben Pfaff wrote: > On Fri, Feb 17, 2017 at 07:34:10AM -0500, Stephen Finucane wrote: > > On Thu, 2017-02-16 at 09:24 -0800, Ben Pfaff wrote: > > > Currently, we have some manpages written directly in nroff. This > > > is > > > an > > > awful format, that is difficult to read and difficult to > > > write. Other > > > manpages are written in a custom XML format that, while it is > > > easier > > > to > > > read and write, isn't any standard format and so we can't expect > > > anyone > > > else (person or program) to understand it. This is not > > > ideal. It's > > > difficult to include either format in the readthedocs > > > documentation, > > > too. > > > > I started on a converter for that XML format but I haven't had a > > chance > > to finish it. The biggest problem I encountered was that rST is > > slightly lossy - it's not possible to nest elements the way you can > > nest XML or HTML so you have to drop some stuff. For example, > > converting '<b><i>' is impossible, since rST doesn't have markup > > for > > bold AND italic. Figuring out what to drop proved tougher than I > > thought. I basically needed to build a parser rather than hacking > > something together with regexes :( > > Hmm. I think that the XML format, in nroff translation, effectively > ends up with whatever is the innermost markup. I don't think it does > anything smarter than that. (I don't even know how to produce > bold-italic in nroff.)
Ah, so a tie in this aspect of the XML vs. rST "debate". I have seen a couple of bold-italic > > > I'm thinking about starting to write manpages in REstructured > > > Text > > > (rst). This would make it much easier to include them in the > > > readthedocs pages, and ReST seems to convert pretty well to nroff > > > for > > > installing as real manpages. For example, try fetching > > > http://docutils.sourceforge.net/sandbox/manpage-writer/input/test > > > .txt > > > , > > > which is a rst file, and then running "rst2man test.txt > > > > test.man" > > > and > > > viewing test.man with "man -l" or "groffer". The output looks > > > fine. > > > > > > I think that all we'd need for this is a build dependency on > > > python-docutils to ensure that rst2man is available at build > > > time. > > > > Pure rST would be my recommendation. Sphinx (python-sphinx) > > supports > > man page output [2] and could be an even better option that > > rst2man. We > > already have this (optional) dependency for the docs. > > Can you help me understand the trade-off? That is, how is one better > than the other? Some advantages that I can think of: - We can use Sphinx directives, such as 'include' to avoid duplication and 'doc' or 'ref' to cross-reference where required - Our man pages will be integrated into the rest of the docs build system - Only one, widely available dependency needed for all documentation: python-sphinx - Sphinx supports multiple output formats - not just roff or HTML. PDF versions of the man pages, for example, would be possible for whoever wanted them As far as downsides go, rST with Sphinx directives can't be rendered without "compiling the docs", unlike pure rST docs. Also, introducing a bug in the docs would now break the global build (maybe a good thing?) > > I do note that Django includes the generated man pages in the repo > > itself [1]. While the general policy for version control is not to > > include anything that's autogenerated, this could make packaging > > and > > installation from source slightly easier by avoiding adding another > > dependency. Then again, Sphinx is widely enough used that we could > > be > > pretty certain it would be available. I'll leave this to you to > > decide. > > We already have a build dependency on Python, so I don't think that > depending on python-docutils would add much to that; it seems like > it's > close to being core Python in any case. I don't know whether adding > sphinx is a big deal. Personally, given the widespread availability of Sphinx (it's been packaged on all major distros for many moons now [*] and easily installed on Windows), I think it's fair to make Sphinx a required dependency for building OVS now. The only platforms I can't find concrete info for are the two BSDs, but they do have Python and therefore should have pip too? > > I have a couple of the man pages already converted to rST so, if > > you're > > happy to wait until after the OpenStack PTG, I could submit these. > > Also > > happy to review if someone else would like to work on it. > > It'd be great to see what you've converted, so that we'd have a head > start. > > I'm going to be out of town through next Wednesday, so I'll probably > be > unresponsive until then. Sure. I'll push it some time early next week once I'm done with the PTG and can clarify their completeness. Stephen --- [*] I chose arbitrarily "old" versions of various distros to validate this, looking for Sphinx >= 1.0: Debian Wheezy - https://packages.debian.org/wheezy/python-sphinx Ubuntu Precise - http://packages.ubuntu.com/precise/python/python-sphin x CentOS 6 (EPEL) - https://centos.pkgs.org/6/epel-x86_64/python-sphinx10 -1.0.8-1.el6.noarch.rpm.html _______________________________________________ dev mailing list [email protected] https://mail.openvswitch.org/mailman/listinfo/ovs-dev
