On 4/28/26 10:55 PM, Mark Michelson wrote: > Thanks for the comments Ilya! > > On Tue, Apr 28, 2026 at 3:14 PM Ilya Maximets <[email protected]> wrote: >> >> On 4/28/26 8:36 PM, Ilya Maximets wrote: >>> On 4/28/26 7:45 PM, Mark Michelson via dev wrote: >>>> This patch set aims to correct errors in ovn-northd documentation. >>>> Specifially, it corrects the following: >>>> >>>> * Add missing/incorrect program options to manpages. For this series, >>>> this includes the ovn-northd, ovn-nb, and ovn-nbctl manpages. >>>> * Correct missing/incorrect program options in usage strings. For this >>>> series, this includes the ovn-northd and ovn-nbctl programs. >>>> >>>> In addition to the above, this series also splits the ovn-northd manpage >>>> in two. The ovn-northd manpage contains only information about running >>>> the ovn-northd application, such as command line options. The new >>>> ovn-logical-flows manpage contains information about the logical flows >>>> that ovn-northd installs. The final commit in this series converts the >>>> ovn-logical-flows manpage input file from XML to rST, since it is more >>>> frequently updated by developers, and rST is much easier to read and >>>> edit than XML. >>>> >>>> One thing this series does NOT try to address is missing information in >>>> the ovn-logical-flows document regarding how certain options affect the >>>> generated logical flows. This can be done in another patch series, and >>>> with the conversion to rST, this will likely be much easier to do. >>>> >>>> About 99% of this series was AI-generated. My contributions are some >>>> clarifications in the commit messages, as well as updating some >>>> ancillary files in the final commit to indicate the requirement for >>>> rst2man. >>> >>> FWIW, we shouldn't add an extra dependency for this. The standard way to >>> build rST man pages is with sphinx and OVN already has all the infra for >>> that in Documentation/automake.mk. The ovn-sim.1 is built this way. >>> Though you'll need to use RST_MANPAGES instead of RST_MANPAGES_NOINST for >>> the northd page, I suppose. You can also find more examples in the >>> Documentation/automake.mk in OVS. >> >> There is also this commit where I converted ovs-actions page from XML >> to rST quite a few years ago (in OVS repo, of course): >> c2fb5bdae6e3 ("ovs-actions: Convert man page from xml to rST.") >> It's not perfect, but can be used as a reference. > > Thanks for the pointers, I'll have a look and see what I can do. > >> >>> >>> The resulted page will be in Documentation/ref, make sure it's properly >>> placed for distribution. Will need an update for Documentation/conf.py >>> and Documentation/ref/index.rst, so it is browse-able in the built >>> documentation on the website. >>> >>> And maybe tell claude to respect the ling length limits where it's not >>> a vebratim code. :) >> >> This last remark is primarily for over-wrapping. The line lengths in the >> new rST doc are all over the place in terms of their length, it's actually >> hard to read. The doc can be likely significantly shorter, if the lines >> are wrapped proerply. E.g. this: >> >> + - If the logical router has rules specified in >> + ``nat`` with >> + ``external_mac``, then >> + those addresses are also used to populate the switch's destination >> + lookup on the chassis where >> + ``logical_port`` is >> + resident. >> >> Can probably be about 3 lines instead of 7. >> >> It also sometimes splits the `` `` blocks, sometimes it doesn't. In a few >> places it might be more beneficial to use proper blocks with :: instead of >> very long `` `` lines. > > Pretty much everything you've said above with regards to formatting is > likely a symptom of > * That's how the original XML document was. Different authors used > different styles, and we weren't always the best at catching when the > line lengths were longer than 80 characters. > * I simply instructed Claude to convert the file, with no direction > with regards to reformatting. Lines that had cumbersome XML tags were > reduced to a few formatting characters, meaning that some lines that > used to be quite long were reduced in size dramatically. The > conversion left those as they were rather than attempting to compact > the text into something resembling a proper document. > > That second bullet point is on me since I should have been more > explicit with my instructions. The big thing I did was to make sure > the resulting manpage looked sane, rather than looking at the source > text to make sure that it was formatted in a reasonable way.
Yeah, the point is that this particular doc is mostly read at the source level by developers and the cover letter here says that it's easier to read rST. But if we don't actually re-format things, we may as well leave it as XML, since proper XML is IMO easier to read than strangely looking rST. > >> >> In general, while claude made a bulk of work, I'd suggest to do a manual >> editing run. It sucks, but the doc can be much better with proper >> formatting, >> highlights and section cross-reference (I don't see links between sections >> in the patch, while they can be there, since rST allows for this kind of >> stuff) that will be very useful in html on the website. Maybe claude can >> help with this stuff too, but it needs to be guided. > > With regards to making the document more readable by respecting the 80 > character limitation, I'll happily do that. > > Were there cross-references in the original XML? I know there were > references to DB tables and columns, but I don't recall if there were > references to other document sections in the original XML. I'm willing > to guide claude through an attempt at adding these. However, if they > weren't there originally, and it requires manually editing several > thousand lines of documentation, then I would argue that adding them > would be a separate scope beyond the initial conversion and could be > done as a follow-up. In other words, if the conversion is not losing > information, then I think it's fine as-is and the niceties can be > added later. The descriptions for the flows in the tables frequently refer to flows in other tables. That what I meant by cross-references, e.g. the text in "Egress Table 6" says "... These registers are used in the <code>Network Function</code> table". In rST that can be a proper reference to the "Egress Table 13: Network Function". The following can be converted into a link to a particular priority rule in the other table if we create an anchor point for it as well: "One priority-1 flow same as ingress <code>Network Function</code>." I agree that it's a bit more work to fully link things to each other, maybe LLMs can help with that. But I'm also pretty sure that nobody will do that in the next 5+ years, if not done now. :) Best regards, Ilya Maximets. _______________________________________________ dev mailing list [email protected] https://mail.openvswitch.org/mailman/listinfo/ovs-dev
