On Mon, Nov 11, 2019 at 03:28:28PM +0100, Ján Tomko wrote: > On Fri, Nov 08, 2019 at 11:21:06AM +0000, Daniel P. Berrangé wrote: > > This refactors existing docs related to the remote driver/daemon and > > URIs. It then also adds a kbase page about RPM package options. > > > > This introduces the use of RST for docs as a replacement for HTML. > > The intent is that all new docs should use RST from this point. > > > > Existing HTML docs are candidates for conversion to RST by anyone > > interested. > > > > Unlike the Perl -> Python conversion, where we already had a mixture of > both, this actually fulfills the prophecy of XKCD #927 [0] > > It would be nice if the first usage of RST actually converted existing > HTML docs, to lead by example, but mostly to demonstrate that it is > reasonably capable of replacing XSLT. I'm happy to convert some existing docs & in fact have already done some work at converting the .pod man pages to .rst with reasonable success. Eliminating POD matches the goals of eliminating perl in general. Personally I don't mind the POD format in terms of its markup / complexity, but RST is better known especially in the python world. So converting the POD to RST addresses XKCD 927. Converting the main docs/*.html is a fairly large job, that I was going look at incrementally over a long time. Possibly it might be possible to use pandoc to autoconvert, as long as the resulting RST isn't too ugly. TBD. I don't think this is neccessary as a blocker for using RST for newly authored docs though. NB writing content is RST is independent of eliminating XSLT as the templating system. Elimination oif XSLT depends what templating system we use, either Sphinx or Pelican - I've not delved into it to figure out which is better, but I don't see any problem with either replacing XSLT as it is not as if we do anything especially clever in XSLT. We're basically just substituting the .html.in files into a single template and generating a table of contents. Regards, Daniel -- |: https://berrange.com -o- https://www.flickr.com/photos/dberrange :| |: https://libvirt.org -o- https://fstop138.berrange.com :| |: https://entangle-photo.org -o- https://www.instagram.com/dberrange :| -- libvir-list mailing list libvir-list@xxxxxxxxxx https://www.redhat.com/mailman/listinfo/libvir-list
