Bug #35713 for bind9-public: permanent href targets in HTML documentation

Hello, I would like to propose small improvement for your BIND ARM in HTML: It would be great if sections and commands had some stable names in <a name="something"> tag. Currently the HTML looks like: <div lang="en" class="sect3"> <div class="titlepage"><div><div><h4 class="title"> <a name="id2583370"></a>Forwarding</h4></div></div></div> <p> The forwarding facility can be used to create a large site-wide Unfortunately, it seems that "id2583370" changes between versions so it is not possible to create truly permanent link to it. It would be really handy to create links like: http://ftp.isc.org/isc/bind9/cur/9.9/doc/arm/Bv9ARM.ch06.html#id2583370 Link targets like #sec-forwarding #option-forward #option-forwarders would be really great. Thank you for your time. -- Petr Spacek @ Red Hat

---

On 8.4.2014 14:37, Chuck Aurora via RT wrote: > On 04/08/2014 06:04 AM, Petr Spacek via RT wrote: >> Ticket <URL: https://bugs.isc.org/Ticket/Display.html?id=35713 > > >> I would like to propose small improvement for your BIND ARM in HTML: >> >> It would be great if sections and commands had some stable names in <a >> name="something"> tag. >> >> Currently the HTML looks like: >> >> <div lang="en" class="sect3"> >> <div class="titlepage"><div><div><h4 class="title"> >> <a name="id2583370"></a>Forwarding</h4></div></div></div> >> <p> >> The forwarding facility can be used to create a large site-wide >> >> Unfortunately, it seems that "id2583370" changes between versions so it >> is not possible to create truly permanent link to it. >> >> It would be really handy to create links like: >> http://ftp.isc.org/isc/bind9/cur/9.9/doc/arm/Bv9ARM.ch06.html#id2583370 > > Permanent links are good, but permanent links with sensible names are > much better. > >> Link targets like >> #sec-forwarding >> #option-forward >> #option-forwarders >> >> would be really great. > > Yes, you're right. This is already under consideration. I myself made > a similar proposal, like the latter one (where all anchor names would > be human readable and make sense.) > > There are macros involved; the same docbook/XML source is used to > create all versions of the ARM, not just the HTML. > >> Thank you for your time. > > Thank you for the suggestion, and yes, time is what it will require. > Right now I'm unable to give you a target date for completion, but > please be assured that this is a long-term project goal. Those > projects have to compete with (and usually lose out to) day-to-day > work like customer support and development / bug fixes. I understand you, sure, time is always a problem. Maybe I can send you some patches if you are willing to accept them. Note that I'm not saying that I will add nice names to all commands/options/sections in the ARM. However I can add names to sections I'm interested in as I go over them. For this, it would be nice to have something like nightly build of docs so I can send you a patch and use the link with nice name the next day or something like that. I'm not going to send you docs patches if I have to wait months to see the nice link on an server because I will have to use the ugly name or copy the text anyway. I'm looking forward for further cooperation on this. Have a nice day! -- Petr Spacek @ Red Hat

---

On 8.4.2014 17:11, Evan Hunt via RT wrote: > Hi Petr, > > On Tue, Apr 08, 2014 at 12:45:42PM +0000, Petr Spacek via RT wrote: >> I understand you, sure, time is always a problem. >> >> Maybe I can send you some patches if you are willing to accept them. > > The person who originally set up our documentation is no longer with > ISC, and I haven't had time to look into the matter and find out *how* > to put permanent human-readable anchors into the xml/docbook files and > have them do the right thing once converted to HTML. If you already > know how, can you send me a sample, and save me the research effort? Sure! All you have to do is to define "id" attribute. E.g.: <chapter id="Bv9ARM.ch01"> <title>Introduction</title> automatically produces metadata for link http://ftp.isc.org/isc/bind9/cur/9.9/doc/arm/Bv9ARM.ch01.html#Bv9ARM.ch01 This works out-of-the-box for standard tags like chapter, section, example, table etc. You can see more examples on http://www.freeipa.org/docs/master/html-desktop/index.html#ex.user-search The respective source is on https://git.fedorahosted.org/cgit/freeipa-docs.git/tree/src/user_guide/en-US/Users.xml#n2364 -- Petr^2 Spacek

---