Mike Kupfer wrote: > I've been working on some changes to the ON Developers Reference > sources, so that it's easy to generate HTML that matches the existing > structure at the ON community site. The idea is that you'd follow these > steps when making changes: > > (edit the XML source) > $ DOCBOOK=<docbook_path> make -e chunks > $ hg stat on-chunks > (upload HTML files that Mercurial reports as changed) > (edit http://www.opensolaris.org/os/community/on/devref_toc/ if needed) > > The "make chunks" step uses a custom table-of-contents file to control > how the HTML is chunked. Then it runs the HTML through a script to fix > up links and remove unwanted tags. > > You may recall that I posted a preliminary webrev for this back in > November[1]. I have finally gotten back to this, and I think it's more > or less done. The overall structure is the same as it was in November. > The changes since then have primarily been tweaks to the link names and > text. The link tweaks were to match what's already posted on the ON > Community site, so as not to break existing bookmarks. The text tweaks > were typo fixes and resolving some conflicts between the XML text and > the posted HTML. > > I've made two webrevs. http://cr.opensolaris.org/~kupfer/devref-chunks/ > has the changes to the DevRef repo.
Should the devref repo have an explicit .hgignore file for rawchunks and cleanchunks dirs? Comments on Makefile, which appear extensive but are really all nits, because obviously you've been building this stuff successfully: 99-100: this can go away now 105: without the $(ALLFILES) dependency, would this be better as a .xml.html suffix rule? 108: It seems a little bit confusing for "all" to not depend on "chunks." Isn't building this for posting a common scenario? (If not, then ignore this comment.) 116/123: the $(CLEANCHUNKDIR) dependency seems like it might be a little bit misplaced, in that it's part of the dependency chain of rawchunks instead of $(ONCHUNKS). Seems like there could be a race condition for a fast, parallel build, where something could fire the actions on 142 (and therefore 136) before 123? (Generally, a $(TGTDIR)/% target with a dynamically created $(TGTDIR) should depend on both $(TGTDIR) and $(SRCDIR)/%.) ...but now that I look at it a little bit more, the rawchunks stuff is strictly an intermediate product. Instead of having raw and clean chunk dirs, why not use xargs to invoke fixup.py on each chunk in turn at the end of the rule on line 117-118? 125-126 and 128-129: these can be combined into a single action if you use $@ in the rule. The "-p" option to mkdir doesn't hurt anything, but isn't needed. 150: I generally don't like wildcards in clean/clobber targets, at least not where people might be doing active work. And isn't the "*~" an artifact of your editor of choice, rather than the build process? > http://cr.opensolaris.org/~kupfer/devref-html/ shows the changes to the > DevRef HTML that's currently posted.[2] > > I'd like to get a final review of this before proceeding. Once this is > done, I can get started on more interesting content changes, like all > the updates to track the move from Teamware to Mercurial. > > Oh, one last question: does anyone care if I squash the deltas > (recommit) before pushing to the DevRef repo? No, that seems reasonable. --Mark > thanks, > mike > > Footnotes: > [1] > http://mail.opensolaris.org/pipermail/on-discuss/2008-November/000480.html > > [2] the Frames view appears to be broken in both webrevs; I don't know > why. Because the files are in the top level directory of the repository, and webrev doesn't generate the correct relative links for the navbar.
