You are viewing a plain text version of this content. The canonical link for it is here.
Posted to docs@httpd.apache.org by Luca Toscano <to...@gmail.com> on 2017/08/11 16:06:46 UTC
mod_md documentation in trunk
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? The naming of the directives might change
in the future, but I wanted to set up the documentation to allow more
people to review/test Stefan's awesome work.
Thanks!
Luca
Re: mod_md documentation in trunk
Posted by Luca Toscano <to...@gmail.com>.
2017-08-16 16:16 GMT+02:00 Luca Toscano <to...@gmail.com>:
>
>
> 2017-08-13 23:11 GMT+02:00 Luca Toscano <to...@gmail.com>:
>
>> Hi again :)
>>
>> 2017-08-11 18:06 GMT+02:00 Luca Toscano <to...@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"><ManagedDomain></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
Re: mod_md documentation in trunk
Posted by Luca Toscano <to...@gmail.com>.
2017-08-13 23:11 GMT+02:00 Luca Toscano <to...@gmail.com>:
> Hi again :)
>
> 2017-08-11 18:06 GMT+02:00 Luca Toscano <to...@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"><ManagedDomain></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
Re: mod_md documentation in trunk
Posted by Luca Toscano <to...@gmail.com>.
Hi again :)
2017-08-11 18:06 GMT+02:00 Luca Toscano <to...@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"><ManagedDomain></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