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 Wed, 16 Aug 2017 14:16:33 GMT
2017-08-13 23:11 GMT+02:00 Luca Toscano <toscano.luca@gmail.com>:

> 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_f
>> ix.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.
>


So I committed all my changes separately to trunk in the following:

http://svn.apache.org/r1805189
http://svn.apache.org/r1805193

Everything works fine and nice, but I just noticed a side effect that it
wasn't intended, namely the section links like
http://httpd.apache.org/docs/trunk/mod/core.html#ifsection (the old ones
didn't have the "section" suffix). This might be resolved adding some
redirects for the old few sections (like
http://httpd.apache.org/docs/trunk/mod/core.html#if ->
http://httpd.apache.org/docs/trunk/mod/core.html#ifsection) but it might
also be possible that the best solution is rollback and find an alternative
solution.

Let me know your thoughts :)

Luca

Mime
View raw message