RFH: manpages in markdown
Hi all, I've started to look at moving away from using docbook for man page generation, and instead using markdown as the base format which can then be converted to nroff and HTML, etc. Using markdown for this seems sensible---using just nroff (or my preference, mdoc) is one solution, but not as accessible to everyone, and since we've a *lot* of options in FVWM, the documentation needs to be easier to manipulate and have others contribute to, hence why I'm keen to go with plain text in this regard. So far, I've got something lashed together, but it is just mechanical conversions at the moment. There's a lot more that needs to happen which I'll outline below. However, I'm hoping I'm not the person to do this, although I'll happily help/mentor anyone who wishes to pick up from where I've started. What I've done so far is used pandoc to convert the existing Docbook files (XML) to Markdown. I've not checked extensively whether this was successful, but by-and-large it seems to have been. Then, I moved all the generated files to a new top-level directory, "manpages" and added a file in there called ORDER which details how the Markdown files should be catted together to form one huge markdown file which will be the fvwm man page. There's a script called 'generate_manpages.sh' which does all of this mechanically. Run it from within the manpages directory. The conversion of markdown -> nroff is done using a program called 'ronn', found here: https://github.com/rtomayko/ronn But all is not perfect. Install 'ronn' and see for yourself what it spits out. Anyone who's interested in this needs to: * Audit the markdown files to ensure the conversion is complete; * Think whether we need all of the individual .md files or whether we can amalgamate. I suspect we can quite a bit. I'm keen not to see one huge file again. * Fix up a lot of warnings from the markdown files converting to nroff; * Hook these things into the buildsystem, removing the Docbook files. Any questions, do please ask. Any offers of help, *definitely* let me know. You can find my efforts here: https://github.com/fvwmorg/fvwm/tree/ta/docs-to-md Specifically, the 'ta/docs-to-md' branch. Kindly, Thomas Adam
Re: FVWM website: WAS: [Re: FVWM code moved to Github]
> "TA" == Thomas Adam writes: TA> I say we trial this, as it's the simplest change, without additional TA> overhead, and we are then directly able to tweak things as we see TA> fit. OK, I'll stick the appropriate A record into DNS shortly. It may, of course, take a while before everyone's caches expire. TA> Jason, are you OK with this? No problem at all. - J<
Re: FVWM website: WAS: [Re: FVWM code moved to Github]
On Mon, Apr 04, 2016 at 11:56:47AM -0600, Jaimos Skriletz wrote: > https://help.github.com/articles/using-a-custom-domain-with-github-pages/ > https://help.github.com/articles/setting-up-your-pages-site-repository/ I say we trial this, as it's the simplest change, without additional overhead, and we are then directly able to tweak things as we see fit. Jason, are you OK with this? Kindly, Thomas Ada
Re: FVWM website: WAS: [Re: FVWM code moved to Github]
On Mon, Apr 4, 2016 at 11:31 AM, Jason L Tibbitts III wrote: > > "JS" == Jaimos Skriletz writes: > > JS> So to complete the switch the fvwm.org domain needs to be pointed > JS> at/redirected to github.io. > > That's easy for me to do, but before I make any changes. > > JS> I think pointing fvwm.org at github would be preferable as to keep > JS> the domain name, but I'm unsure of anything that would need to be > JS> done on github.io end to accept the fvwm.org as a virtual host and > JS> point it to the correct location. > > Could someone triple check on that? > > Here is the documentation: https://help.github.com/articles/using-a-custom-domain-with-github-pages/ https://help.github.com/articles/setting-up-your-pages-site-repository/ From the DNS end you just need to set up the appropriate A, ANAME, ALIAS record in the DNS. >From Git repo end there needs to be a single file CNAME with the contents ` fvwm.org` as a single line in that file added to the fvwmorg.gethub.io source. I will add this later tonight when I get home (and test it works) before you need to update the DNS. So it seems easy enough. Only thing It is not clear about what ip to point at. I would assume the ip that fvwmorg.gethub.io is pointing at. jaimos
Re: FVWM website: WAS: [Re: FVWM code moved to Github]
> "JS" == Jaimos Skriletz writes: JS> So to complete the switch the fvwm.org domain needs to be pointed JS> at/redirected to github.io. That's easy for me to do, but before I make any changes. JS> I think pointing fvwm.org at github would be preferable as to keep JS> the domain name, but I'm unsure of anything that would need to be JS> done on github.io end to accept the fvwm.org as a virtual host and JS> point it to the correct location. Could someone triple check on that? JS> The other option is have fvwm.org redirect to the above domain name. I can do that as well. Just let me know. - J<
