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.) > > 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? > 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. > 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. _______________________________________________ dev mailing list [email protected] https://mail.openvswitch.org/mailman/listinfo/ovs-dev
