mod_md documentation in trunk

classic Classic list List threaded Threaded
4 messages Options
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

mod_md documentation in trunk

Luca Toscano
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 
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: mod_md documentation in trunk

Luca Toscano
Hi again :)

2017-08-11 18:06 GMT+02:00 Luca Toscano <[hidden email]>:
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 

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: mod_md documentation in trunk

Luca Toscano


2017-08-13 23:11 GMT+02:00 Luca Toscano <[hidden email]>:
Hi again :)

2017-08-11 18:06 GMT+02:00 Luca Toscano <[hidden email]>:
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.


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


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 

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: mod_md documentation in trunk

Luca Toscano


2017-08-16 16:16 GMT+02:00 Luca Toscano <[hidden email]>:


2017-08-13 23:11 GMT+02:00 Luca Toscano <[hidden email]>:
Hi again :)

2017-08-11 18:06 GMT+02:00 Luca Toscano <[hidden email]>:
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.


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


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.

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


Luca
Loading...