BIND9-ARM (HTML) feature request: better hyperlinking in/of chapter 6

[Jeremy C. Reed]

On Wed, 20 Nov 2013, /dev/rob0 wrote:

> Chapter 6 is the comprehensive configuration reference. What I'd like 
> to see is more (and plain-language, consistent) hyperlinking. The 
> basic idea is that any named.conf setting could be found at an 
> anchor:
> 
> Bv9ARM.ch06.html#that-setting

Yes that would be great. We do something similar with the unique log 
messages for BIND10 and Kea; for example:

http://bind10.isc.org/docs/bind10-messages.html#AUTH_XFRIN_CHANNEL_CREATED
http://bind10.isc.org/docs/bind10-messages.html#XFROUT_IXFR_NO_ZONE

The corresponding docbook code was like:

<varlistentry id="AUTH_XFRIN_CHANNEL_CREATED">
...
<varlistentry id="XFROUT_IXFR_NO_ZONE">

> This sounds grand and relatively simple, but in practice it will
> require some thought and work. For example, we have "Grammar" and 
> "Definition and Usage" subsections for each "Statement" section. 
> Which one would we link to? Ideally, both, but we'd have to think 
> about a good anchor naming scheme. I'd say that the name in each 
> "Grammar" should hyperlink to each "Definition and Usage" name and 
> vice versa.

I had thought about this several times. I published a print book based 
on the ARM and considered having the grammar for a specific item 
statement included next to the corresponding documentation -- so you 
don't have to look in multiple places.

> Also, what do we do in the case where the same setting is usable in 
> more than one context? Looking at "Zone Options", with numerous "See 
> the description of ...", this would actually help, because it would 
> take you directly to the setting rather than to the subsection 
> heading.

Yes. I did a lot of work on this also, but never made it into the 
released ARM.

By the way, I have found that the maintained dblatex 
(http://dblatex.sourceforge.net/) framework is easier and more reliable 
to use than the existing db2latex stylesheets. Hopefully someday I can 
finish the conversion of our Makefiles to use it instead (or as an 
alternative).

Thank you much for your suggestions and potential work. If you have any 
questions or need assistance with the PDF/HTML builds, please let me 
know.  (I can also share with you my detailed plans also.)