You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cvs@httpd.apache.org by jc...@apache.org on 2017/05/04 23:55:48 UTC
svn commit: r1793940 - in /httpd/docs-build/trunk: deps.xml lib/allmodules.pl
Author: jchampion
Date: Thu May 4 23:55:48 2017
New Revision: 1793940
URL: http://svn.apache.org/viewvc?rev=1793940&view=rev
Log:
override index: add deps and exclude from all-modules list
Modified:
httpd/docs-build/trunk/deps.xml
httpd/docs-build/trunk/lib/allmodules.pl
Modified: httpd/docs-build/trunk/deps.xml
URL: http://svn.apache.org/viewvc/httpd/docs-build/trunk/deps.xml?rev=1793940&r1=1793939&r2=1793940&view=diff
==============================================================================
--- httpd/docs-build/trunk/deps.xml (original)
+++ httpd/docs-build/trunk/deps.xml Thu May 4 23:55:48 2017
@@ -65,6 +65,7 @@
<targetfileset dir="../"
includes="mod/index${outputext.@{lang}}
mod/directives${outputext.@{lang}}
+ mod/overrides${outputext.@{lang}}
mod/quickreference${outputext.@{lang}}
sitemap${outputext.@{lang}}"
excludes="${ap.noxml.@{lang}}" />
@@ -79,6 +80,7 @@
<targetfileset dir="../"
includes="mod/index${outputext.@{lang}}
mod/directives${outputext.@{lang}}
+ mod/overrides${outputext.@{lang}}
mod/quickreference${outputext.@{lang}}
sitemap${outputext.@{lang}}"
excludes="${ap.noxml.@{lang}}" />
@@ -130,6 +132,15 @@
excludes="${ap.noxml.@{lang}}" />
</dependset>
+ <!-- override index -->
+ <dependset>
+ <srcfileset dir="../style/xsl"
+ includes="overrideindex.xsl" />
+ <targetfileset dir="../"
+ includes="mod/overrides${outputext.@{lang}}"
+ excludes="${ap.noxml.@{lang}}" />
+ </dependset>
+
<!-- index page -->
<dependset>
<srcfileset dir="../style/xsl"
@@ -200,6 +211,7 @@
excludes="mod/*-dict${outputext.@{lang}}
mod/index${outputext.@{lang}}
mod/directives${outputext.@{lang}}
+ mod/overrides${outputext.@{lang}}
mod/quickreference${outputext.@{lang}}
${ap.noxml.@{lang}}" />
</dependset>
Modified: httpd/docs-build/trunk/lib/allmodules.pl
URL: http://svn.apache.org/viewvc/httpd/docs-build/trunk/lib/allmodules.pl?rev=1793940&r1=1793939&r2=1793940&view=diff
==============================================================================
--- httpd/docs-build/trunk/lib/allmodules.pl (original)
+++ httpd/docs-build/trunk/lib/allmodules.pl Thu May 4 23:55:48 2017
@@ -65,12 +65,12 @@ opendir(DIR, $curpath)
closedir(DIR)
or die "could not close directory '$curpath' ($!), stopped";
-push @suffix => map { s/^(?:index|directives|quickreference)\.xml//; $_ }
- grep /^(?:index|directives|quickreference)\.xml/
+push @suffix => map { s/^(?:index|directives|quickreference|overrides)\.xml//; $_ }
+ grep /^(?:index|directives|quickreference|overrides)\.xml/
=> @{[ @mod_files ]}; # copy, because $_ will be modified inline
# keep only real module files in @mod_files
-@mod_files = grep !/^(?:index|directives|quickreference)\.xml/
+@mod_files = grep !/^(?:index|directives|quickreference|overrides)\.xml/
=> grep !/-dict\.xml/
=> grep !/^allmodules\.xml/
=> @mod_files;
Re: svn commit: r1793940 - in /httpd/docs-build/trunk: deps.xml
lib/allmodules.pl
Posted by Jacob Champion <ch...@gmail.com>.
On 05/08/2017 02:18 PM, Jacob Champion wrote:
> For this particular change, if someone forgets to update their build
> directory and changes an <override> tag, there won't be any error
> message. But the new override index will silently fail to be updated,
> and an incorrect index will be checked in. Not great for a piece of
> security-related documentation.
I think half of this (minus the incorrect override index being checked
in) just happened with r1799455. Luckily there were no <override> tag
changes to be made.
--Jacob
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: svn commit: r1793940 - in /httpd/docs-build/trunk: deps.xml
lib/allmodules.pl
Posted by Jacob Champion <ch...@gmail.com>.
On 05/06/2017 10:15 AM, André Malo wrote:
> The libs are coupled with the build files (ant files and stuff). Thatswhy
> they are together. The Separating them creates the same issue again, I'd
> say.
A one-way dependency to an abstraction (like the Xalan-J API) is fine in
my book. Coupling back the other way -- not so much. Libraries shouldn't
be tightly coupled to clients, and that's what we have now with
deps.xml, allmodules.pl, et al.
> I'm still not getting what exactly do you want to move
I'm not proposing moving anything right this instant. But ideally,
anything that hardcodes references to the httpd repo belongs in the
httpd repo. Scripts that are truly designed to be general-purpose can be
refactored to take arguments from the client (httpd) and stay in lib/.
Anything that isn't actually general-purpose (e.g. deps.xml) gets moved.
> and what problem we're actually trying to solve.
As long as you keep tightly-coupled components in lockstep, there won't
be a visible problem. The "problem" is the tight coupling itself, which
causes maintenance headaches and bugs if the two sides get out of sync
for whatever reason.
For this particular change, if someone forgets to update their build
directory and changes an <override> tag, there won't be any error
message. But the new override index will silently fail to be updated,
and an incorrect index will be checked in. Not great for a piece of
security-related documentation.
> Branch compatibility is what I got so far.
> Is that a real problem?
As it stands, we have to ensure that the same dependency list and the
same build machinery applies correctly to all branches. That requirement
isn't giving us any benefit, as far as I can tell. As for whether it's a
"real" problem... well, it doesn't seem to have bitten us yet. But I
prefer being proactive when it comes to architecture.
Again, though: it's not like I'm jumping into massive code upheaval
starting tomorrow. I just want to get a feel for why things are this
way, and if it's due to deliberate design or if it's just how things
fell out, and then I'll put it on my ever-growing list of TODOs.
--Jacob
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: svn commit: r1793940 - in /httpd/docs-build/trunk: deps.xml lib/allmodules.pl
Posted by André Malo <nd...@perlig.de>.
* Jacob Champion wrote:
> [Re-cc'ing docs. Sorry.]
>
> On 05/05/2017 01:34 AM, André Malo wrote:
> > Well... It was a split-project back then (in CVS even... :-)). I'm
> > also not
> > sure we want all those jar files and stuff in the main repo. Most
> > people neither use nor need it.
>
> I don't mind having the binaries in a separate place, so much as I mind
> having the text-based stuff there that's tightly coupled to the rest of
> the documentation and code. What we have right now is equivalent to
> putting your project's Makefile into a separate repository and then
> trying to make sure it works correctly for every branch at once.
>
> > Note that once the changes are finalized, you can run `build tools`
> > and upload
> > the package to dist/docs
>
> Ah, so there's a dist package for people who can't check out docs-build?
Yes.
( http://httpd.apache.org/docs-project/docsformat.html )
> If we moved some files out of docs-build into httpd, would that affect
> them negatively?
I guess not.
>
> To put it another way: if we were to move all the text files and scripts
> from the docs-build root directory into a docs/manual/build folder in
> httpd, and left the docs-build lib folder that has all the third-party
> dependencies and jars and stuff (so that you still had to sync that down
> from SVN), would there be any downsides compared to today?
The libs are coupled with the build files (ant files and stuff). Thatswhy
they are together. The Separating them creates the same issue again, I'd
say.
I'm still not getting what exactly do you want to move and what problem
we're actually trying to solve. Branch compatibility is what I got so far.
Is that a real problem?
Cheers,
--
> Rätselnd, was ein Anthroposoph mit Unterwerfung zu tun hat...
^^^^^^^^^^^^
[...] Dieses Wort gibt so viele Stellen für einen Spelling Flame her, und
Du gönnst einem keine einzige. -- Jean Claude und David Kastrup in dtl
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: svn commit: r1793940 - in /httpd/docs-build/trunk: deps.xml
lib/allmodules.pl
Posted by Jacob Champion <ch...@gmail.com>.
[Re-cc'ing docs. Sorry.]
On 05/05/2017 01:34 AM, André Malo wrote:
> Well... It was a split-project back then (in CVS even... :-)). I'm
> also not
> sure we want all those jar files and stuff in the main repo. Most people
> neither use nor need it.
I don't mind having the binaries in a separate place, so much as I mind
having the text-based stuff there that's tightly coupled to the rest of
the documentation and code. What we have right now is equivalent to
putting your project's Makefile into a separate repository and then
trying to make sure it works correctly for every branch at once.
> Note that once the changes are finalized, you can run `build tools`
> and upload
> the package to dist/docs
Ah, so there's a dist package for people who can't check out docs-build?
If we moved some files out of docs-build into httpd, would that affect
them negatively?
To put it another way: if we were to move all the text files and scripts
from the docs-build root directory into a docs/manual/build folder in
httpd, and left the docs-build lib folder that has all the third-party
dependencies and jars and stuff (so that you still had to sync that down
from SVN), would there be any downsides compared to today?
--Jacob
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: svn commit: r1793940 - in /httpd/docs-build/trunk: deps.xml
lib/allmodules.pl
Posted by Jacob Champion <ch...@gmail.com>.
[Re-cc'ing docs. Sorry.]
On 05/05/2017 01:34 AM, André Malo wrote:
> Well... It was a split-project back then (in CVS even... :-)). I'm
> also not
> sure we want all those jar files and stuff in the main repo. Most people
> neither use nor need it.
I don't mind having the binaries in a separate place, so much as I mind
having the text-based stuff there that's tightly coupled to the rest of
the documentation and code. What we have right now is equivalent to
putting your project's Makefile into a separate repository and then
trying to make sure it works correctly for every branch at once.
> Note that once the changes are finalized, you can run `build tools`
> and upload
> the package to dist/docs
Ah, so there's a dist package for people who can't check out docs-build?
If we moved some files out of docs-build into httpd, would that affect
them negatively?
To put it another way: if we were to move all the text files and scripts
from the docs-build root directory into a docs/manual/build folder in
httpd, and left the docs-build lib folder that has all the third-party
dependencies and jars and stuff (so that you still had to sync that down
from SVN), would there be any downsides compared to today?
--Jacob
Re: svn commit: r1793940 - in /httpd/docs-build/trunk: deps.xml lib/allmodules.pl
Posted by William A Rowe Jr <wr...@rowe-clan.net>.
On May 8, 2017 18:15, "Jacob Champion" <ch...@gmail.com> wrote:
On 05/05/2017 04:42 PM, William A Rowe Jr wrote:
> I've been similarly confused. It's obvious that the XML sources have no
> context without the XSLT and build stack.
>
For XSLT, agreed. But as Andre points out there is a way to use the XML
without the build stack, as long as you have a capable browser.
There are a couple ways we could slice this, including pulling .XML out
> from all the packages which won't ship the transformations.
>
I'm kind of hoping for the opposite of this -- push more of the context
that belongs with the XML files into the httpd repo, and remove anything
from the build repo that shouldn't be generalized to all branches of the
documentation.
Sounds like the right (if not simplest) approach.
Re: svn commit: r1793940 - in /httpd/docs-build/trunk: deps.xml
lib/allmodules.pl
Posted by Jacob Champion <ch...@gmail.com>.
On 05/05/2017 04:42 PM, William A Rowe Jr wrote:
> I've been similarly confused. It's obvious that the XML sources have no
> context without the XSLT and build stack.
For XSLT, agreed. But as Andre points out there is a way to use the XML
without the build stack, as long as you have a capable browser.
> There are a couple ways we could slice this, including pulling .XML out
> from all the packages which won't ship the transformations.
I'm kind of hoping for the opposite of this -- push more of the context
that belongs with the XML files into the httpd repo, and remove anything
from the build repo that shouldn't be generalized to all branches of the
documentation.
--Jacob
Re: svn commit: r1793940 - in /httpd/docs-build/trunk: deps.xml lib/allmodules.pl
Posted by William A Rowe Jr <wr...@rowe-clan.net>.
On May 5, 2017 9:28 AM, "Jacob Champion" <ch...@gmail.com> wrote:
On 05/05/2017 01:34 AM, André Malo wrote:
> Well... It was a split-project back then (in CVS even... :-)). I'm also not
> sure we want all those jar files and stuff in the main repo. Most people
> neither use nor need it.
>
I don't mind having the binaries in a separate place, so much as I mind
having the text-based stuff there that's tightly coupled to the rest of the
documentation and code. What we have right now is equivalent to putting
your project's Makefile into a separate repository and then trying to make
sure it works correctly for every branch at once.
I've been similarly confused. It's obvious that the XML sources have no
context without the XSLT and build stack.
There are a couple ways we could slice this, including pulling .XML out
from all the packages which won't ship the transformations.
What I do agree with is treating build/ as an external, leveraging the same
sources (and some .jars) for the many trees we maintain.
Re: svn commit: r1793940 - in /httpd/docs-build/trunk: deps.xml
lib/allmodules.pl
Posted by Jacob Champion <ch...@gmail.com>.
On 05/05/2017 01:34 AM, André Malo wrote:
> Well... It was a split-project back then (in CVS even... :-)). I'm also not
> sure we want all those jar files and stuff in the main repo. Most people
> neither use nor need it.
I don't mind having the binaries in a separate place, so much as I mind
having the text-based stuff there that's tightly coupled to the rest of
the documentation and code. What we have right now is equivalent to
putting your project's Makefile into a separate repository and then
trying to make sure it works correctly for every branch at once.
> Note that once the changes are finalized, you can run `build tools` and upload
> the package to dist/docs
Ah, so there's a dist package for people who can't check out docs-build?
If we moved some files out of docs-build into httpd, would that affect
them negatively?
To put it another way: if we were to move all the text files and scripts
from the docs-build root directory into a docs/manual/build folder in
httpd, and left the docs-build lib folder that has all the third-party
dependencies and jars and stuff (so that you still had to sync that down
from SVN), would there be any downsides compared to today?
--Jacob
Re: svn commit: r1793940 - in /httpd/docs-build/trunk: deps.xml lib/allmodules.pl
Posted by André Malo <nd...@perlig.de>.
* Jacob Champion wrote:
> [crossposting dev@ and docs@]
>
> On 05/04/2017 04:55 PM, jchampion@apache.org wrote:
> > Author: jchampion
> > Date: Thu May 4 23:55:48 2017
> > New Revision: 1793940
> >
> > URL: http://svn.apache.org/viewvc?rev=1793940&view=rev
> > Log:
> > override index: add deps and exclude from all-modules list
>
> I found it a little weird that the XSLT dependencies aren't part of the
> httpd project, but exist in a separate repo... it doesn't seem like
> 2.x.y and trunk should be required to have the same dependency graph, or
> even the same processing scripts. And anyone who forgets to do an `svn
> up` in their build directory is likely to break things after my commits
> today.
Well... It was a split-project back then (in CVS even... :-)). I'm also not
sure we want all those jar files and stuff in the main repo. Most people
neither use nor need it.
Note that once the changes are finalized, you can run `build tools` and upload
the package to dist/docs
IMHO as long as we can maintain it as a single toolset, we should keep it that
way (we can also change behaviour based on the version property).
Cheers,
--
"Das Verhalten von Gates hatte mir bewiesen, dass ich auf ihn und seine
beiden Gefährten nicht zu zählen brauchte" -- Karl May, "Winnetou III"
Im Westen was neues: <http://pub.perlig.de/books.html#apache2>
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: svn commit: r1793940 - in /httpd/docs-build/trunk: deps.xml lib/allmodules.pl
Posted by André Malo <nd...@perlig.de>.
* Jacob Champion wrote:
> [crossposting dev@ and docs@]
>
> On 05/04/2017 04:55 PM, jchampion@apache.org wrote:
> > Author: jchampion
> > Date: Thu May 4 23:55:48 2017
> > New Revision: 1793940
> >
> > URL: http://svn.apache.org/viewvc?rev=1793940&view=rev
> > Log:
> > override index: add deps and exclude from all-modules list
>
> I found it a little weird that the XSLT dependencies aren't part of the
> httpd project, but exist in a separate repo... it doesn't seem like
> 2.x.y and trunk should be required to have the same dependency graph, or
> even the same processing scripts. And anyone who forgets to do an `svn
> up` in their build directory is likely to break things after my commits
> today.
Well... It was a split-project back then (in CVS even... :-)). I'm also not
sure we want all those jar files and stuff in the main repo. Most people
neither use nor need it.
Note that once the changes are finalized, you can run `build tools` and upload
the package to dist/docs
IMHO as long as we can maintain it as a single toolset, we should keep it that
way (we can also change behaviour based on the version property).
Cheers,
--
"Das Verhalten von Gates hatte mir bewiesen, dass ich auf ihn und seine
beiden Gefährten nicht zu zählen brauchte" -- Karl May, "Winnetou III"
Im Westen was neues: <http://pub.perlig.de/books.html#apache2>
Re: svn commit: r1793940 - in /httpd/docs-build/trunk: deps.xml
lib/allmodules.pl
Posted by Jacob Champion <ch...@gmail.com>.
[crossposting dev@ and docs@]
On 05/04/2017 04:55 PM, jchampion@apache.org wrote:
> Author: jchampion
> Date: Thu May 4 23:55:48 2017
> New Revision: 1793940
>
> URL: http://svn.apache.org/viewvc?rev=1793940&view=rev
> Log:
> override index: add deps and exclude from all-modules list
I found it a little weird that the XSLT dependencies aren't part of the
httpd project, but exist in a separate repo... it doesn't seem like
2.x.y and trunk should be required to have the same dependency graph, or
even the same processing scripts. And anyone who forgets to do an `svn
up` in their build directory is likely to break things after my commits
today.
Would there be any interest here in bringing parts of the docs-build
repo back into the fold? (Or a history lesson into why things are this way?)
--Jacob
Re: svn commit: r1793940 - in /httpd/docs-build/trunk: deps.xml
lib/allmodules.pl
Posted by Jacob Champion <ch...@gmail.com>.
[crossposting dev@ and docs@]
On 05/04/2017 04:55 PM, jchampion@apache.org wrote:
> Author: jchampion
> Date: Thu May 4 23:55:48 2017
> New Revision: 1793940
>
> URL: http://svn.apache.org/viewvc?rev=1793940&view=rev
> Log:
> override index: add deps and exclude from all-modules list
I found it a little weird that the XSLT dependencies aren't part of the
httpd project, but exist in a separate repo... it doesn't seem like
2.x.y and trunk should be required to have the same dependency graph, or
even the same processing scripts. And anyone who forgets to do an `svn
up` in their build directory is likely to break things after my commits
today.
Would there be any interest here in bringing parts of the docs-build
repo back into the fold? (Or a history lesson into why things are this way?)
--Jacob
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org