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 Sat, 19 Aug 2017 12:34:34 GMT
2017-08-16 16:16 GMT+02:00 Luca Toscano <toscano.luca@gmail.com>:

>
>
> 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/t
> runk/mod/core.html#if -> http://httpd.apache.org/doc
> s/trunk/mod/core.html#ifsection) but it might also be possible that the
> best solution is rollback and find an alternative solution.
>

Last changes in trunk restored the old links and kept the new ones:

http://svn.apache.org/r1805372
http://svn.apache.org/r1805376

Luca

Mime
View raw message