nut
nut copied to clipboard
networkupstools
[WIP] Rename README to allow GitHub to render as AsciiDoc
NOTE: Work In Progress (WIP). I don't like that the links do not work - but if I fix them to point to files, then the generated HTML documentation breaks.
@zykh, any ideas? I know you have done some work with AsciiDoc and GitHub in the DDL. Could we define linkdoc: and linkman: such that they work in both environments?
As far as I know GitHub doesn't support custom macros - what we could do is to use attributes that conditionally expand to links on GitHub and to our macros when generating docs. This approach should work properly as long as we use them in contexts where attributes are evaluated and substituted before macros.
Here's a try at it: https://github.com/zykh/nut/tree/rename_readme ...with or without the last commit (alas, linkman macros cannot be easily replaced by a common attribute so I had to double it).
I've also tried to fix cross references, but that has forced me to change the way chunked pages are named and that will mess-up older links (on other sites, mailing list, ...) and, oviously, the links on GitHub won't work unless we update the website.
@zykh I did, briefly. I've been meaning to spend more time looking at the AsciiDoc attribute syntax so that I understand its capabilities.
I also think that changing links might depend on how easy it is to administer the new website. I added a lot of redirects from the old Trac instance over to GitHub commits, and it wasn't too bad, but that's because I have access to the old server, and can mine the logs for common links.
@aquette: thoughts? Would anyone from Eaton be able to help with rewriting links and verifying them?
I want to get the next release out before spending time on this, but I do think that it is worth overhauling the README so that it renders as AsciiDoc (or Markdown) in the NUT repository. If that means adding a few static links to the production version of the website (only in the README), so be it.
I think that sort of change would go nicely with https://github.com/networkupstools/nut-website/issues/18
@clepple : GitHub won't let me edit the PR to resolve conflicts against current NUT master...
I’m not in front of a computer at the moment, but the WIP was probably referring to me not wanting to break the Asciidoc website- I was mainly pushing that commit to see how GitHub rendered it. If this is simpler than I am assuming it to be, then I am fine with a new PR superseding this one. (However, be forewarned that there is a lot of noise when comparing the old website to newly rendered HTML)
How is this related to #669? Does that complement or supercede this?
Maybe I can try rebasing this into a new MR unless someone is already working on it?
Not actively at the moment. As noted in comments, this is not so much about renaming files and updating their names in recipes and links, as about ensuring that github does a reasonable job at rendering at least single pages, and more that html cross-links and pdf chapters still work. And something about custom macros someplace. And NUT website generation as a big cherry on top to keep working :)
So maybe it is a low-hanging fruit, maybe not - gotta try, regenerate pages and books, compare to standard build products... maybe just never got around to do that all carefully. Needs a big concentrated time slot at least.