Why do we have an "includes" directory in docs ?

[Eric S. Raymond]

Sanjeev Gupta <ghane0 at gmail.com>:
> On Tue, Nov 29, 2016 at 10:29 PM, Sanjeev Gupta <ghane0 at gmail.com> wrote:
> 
> >
> > I have fixed most of the misspellings, but there is a bigger issue I am
> > facing now.  As an example, please see:
> >
> > https://docs.ntpsec.org/latest/confopt.html
> >
> > This is generated from confopt.txt , which gets its "Related Links" from:
> >   include::includes/confopt.txt[]
> >
> > which has (an example):
> >   * link:confopt.html#server[server - configure client association]
> >
> > For reasons not clear to me at first sight, the anchor
> > "confopt.html#server" does not link back to the right paragraph in
> > confopt.html.  It goes nowhere, in fact.
> >
> 
> I think the answer is at: https://www.w3.org/TR/xhtml1/guidelines.html#C_8
> 
> The toolchain seems to be producing HTML without "id=", and in some cases,
> at the wrong place.  I have been reading asciidoc documentation all day,
> and am quite confused now :-(
> 
> See commit:
> https://gitlab.com/NTPsec/ntpsec/commit/df1b84a68058be5d855b106c91714ad9743e4b21
> for an example of non-intutive-ness.  I am pushing some simple fixes now,
> but not touching the anchor issue any more (I might break the man pages,
> etc)
> 
> Help?

An ASCIIDoc, writing an enclosure of the form [[foo]] is how you force an id
anchor to be generated and that point; anchor:foo[] will also work.

I think the reason confopt.html#server doesn't point ansywhere is that there's
no [[server]] anchor in the target file.  I see this instead:

[[option]]
== Server Command Options ==

I've written some help for you.  If you do "waf linkcheck" in the root
directory, you will get a report on unresolved links.  If you run it with
compile-command in an Emacs buffer, you will be able to step through them
as you would compiler error messages.
-- 
		<a href="http://www.catb.org/~esr/">Eric S. Raymond</a>