httpd-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Luca Toscano <toscano.l...@gmail.com>
Subject Re: mod_md documentation in trunk
Date Sun, 13 Aug 2017 21:11:57 GMT
Hi again :)

2017-08-11 18:06 GMT+02:00 Luca Toscano <toscano.luca@gmail.com>:

> Hi everybody,
>
> as you probably know Stefan added the first implementation of mod_md in
> trunk plus some documentation. I tried to build it and got rid of some
> errors with http://home.apache.org/~elukey/httpd-trunk-mod_md-doc_
> fix.patch but then I can still see the following after running build.sh
> validate-xhtml:
>
> validate-xhtml:
> [xmlvalidate] [..path..]/docs/manual/mod/mod_md.html.en:170:79: Attribute
> value "ManagedDomain" of type ID must be unique within the document.
> [xmlvalidate] [..path..]/docs/manual/mod/mod_md.html.en:170:148:
> Attribute value "manageddomain" of type ID must be unique within the
> document.
> [xmlvalidate] [..path..]/docs/manual/mod/mod_md.html.en:193:79: Attribute
> value "ManagedDomain" of type ID must be unique within the document.
> [xmlvalidate] [..path..]/docs/manual/mod/mod_md.html.en:193:140:
> Attribute value "manageddomain" of type ID must be unique within the
> document.
> [xmlvalidate] [..path..]/docs/manual/mod/mod_md.html.en:264:79: Attribute
> value "ManagedDomain" of type ID must be unique within the document.
> [xmlvalidate] [..path..]/docs/manual/mod/mod_md.html.en:264:148:
> Attribute value "manageddomain" of type ID must be unique within the
> document.
> [xmlvalidate] [..path..]/docs/manual/mod/mod_md.html.en is not a valid
> XML document
> [xmlvalidate] 806 file(s) have been successfully validated.
>
> From synopsis.xml it seems to me that the problem is the fact that now we
> have a directive called ManagedDomain and a directive/context-block called
> <ManagedDomain> that end up with the same id since they share the name (and
> also for some reason duplicate HTML, the sections are repeated two times).
>
> Any idea about how to fix this?
>

I found a solution that works with this patch:
http://home.apache.org/~elukey/httpd-trunk-mod_md-doc_fix.patch

There are a couple of things that I needed to do but they should allow
having in the same document two directives like ManagedDomain and
<ManagedDomain> (the latter is type=section):

- Replace <xsl:apply-templates select="$this[name=current()/name]" />
with <xsl:apply-templates select="." />, since the former, when running in
a for loop, causes duplicates when two directives share the same name. I
hope that using select="." is fine, looking forward to feedback from more
experienced docs committers.

- Change the id of each <a> block with the concatenation of name + id, that
in this case would be "ManagedDomain" and "ManagedDomainsection" (and their
lowercase counterparts). Example from the transformation:

<div class="directive-section"><h2><a name="ManagedDomainsection"
id="ManagedDomainsection">&lt;ManagedDomain&gt;</a> <a
name="manageddomainsection" id="manageddomainsection">Directive</a></h2>

The good thing about this change is that validate-xhtml will keep failing
if two directives are copied/pasted by accident (or simply repeated) but it
won't for legitimate cases like the ManagedDomain and <ManagedDomain> of
mod_md.

Hope that what I wrote makes sense, will wait a bit before pushing my
changes to gather some feedback.

Thanks!

Luca

Mime
View raw message