avalon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Leo Simons <leosim...@apache.org>
Subject Re: Xdocs Standards
Date Fri, 19 Jul 2002 08:34:31 GMT
I want the forrest DTDs, and I want nothing more and nothing less.
They're clear, they fit our needs exactly, they've been thought out,
they are similar to document-v10, they're complete, and it is highly
likely there will be tools to auto-check and generate nice errors.

I am not going to put in the work to make all the documentation conform
(doing this for anakia is a problem as current jakarta-site2 has no DTD
so you cannot automate properly) until forrest gets a release, though.

I honestly don't care at this point about the format of
project/book/menu.xml; these files are not so difficult to maintain.
What I do want ASAP is to get every single <a> and <hX>, <div> etc gone
from the documentation, and that will require a DTD to enforce.

If you want to put in the work to unify book/project.xml, please do so
though! I'd suggest using the book2project.xsl Pete's already written to
start with.

FWIW, I feel these files need to be either at the complete top of what
they manage (ie like build.xml in CVS root) or in a dedicated common
subdirectory. The advantage of the subdirectory is that file masks are
easier to set up.

[FRUSTRATED RANT BELOW]

If there really is something who is willing to put a lot of time of
effort in, here's what I want:

jakarta-avalon-site/src/xdocs
	/avalon
		/project
			menu.xml
			document-v11.dtd (if it is really required
			   everywhere as has been mentioned,
			   otherwise just reference an URI in the
			   xdocs -- like it should be for DTDs)
		index.xml
		features.xml
		todo.xml
		...

jakarta-avalon-site/tools
	{blah}.xml (ant buildfile for doc generation)
	{blah2}.xml (ant buildfile for alternate doc generation)
	
	/lib/common
		xerces.jar
		xalan.jar
		{whatever}.jar
	/lib/{blah}
		{blah}.jar
	/lib/{blah2}
		{blah2}.jar

	/skins/{blah}
		/{commonskinname}
			{dontcarehowthisworks}.*
	
	/skins/{blah2}
		/{commonskinname}
			{dontcarehowthisworks}.*

jakarta-avalon/src/xdocs
		/framework
			/project
				menu.xml

			index.xml
			features.xml
			todo.xml
			...
	
jakarta-avalon-excalibur/site/src/xdocs
	/avalon
		/excalibur
			/project
				menu.xml

			index.xml
			features.xml
			todo.xml
			...

jakarta-avalon-excalibur/tweety/src/xdocs
	/avalon
		/excalibur
			/tweety/
				/project
					menu.xml

				index.xml
				features.xml
				todo.xml
				...

and inside my build.xml file:

<target name="html-docs">
	<ant file="${avalon-site}/${doc.tool}.xml" inherit="false"
			target="html-docs">
		<property name="input" value="${src.xdocs}"/>
		<property name="output" value="${build.docs}"/>
		<property name="skin" value="${use.skin}"/>
	</ant>
</target>

<target name="install-docs">
	<ant file="${avalon-site}/${doc.tool}.xml" inherit="false"
			target="install-docs">
		<property name="input" value="${build.docs}"/>
	</ant>
</target>


or something similar. In other words, I want my documentation process to
look like this:

- create an xdocs directory,

- mirror the jakarta.apache.org site layout there,

- create a project/menu.xml,

- create some xml documents conforming to doc-v11.dtd (using a
validating tool if possible),

- put them in the menu.xml (I don't want this auto-generated as you need
to express important grouping and ordering information in there), 

- scatter the place with other stuff (images and the like) and put them
anywhere I want

- add a small snippet to my ant buildfile (or check a checkbox in a
centipede GUI); don't really care what it looks like

- optionally specify a ${doc.tool} as we all seem to want different
tools

- type 'ant docs' to build docs. (I'd like this to take no more than
three times as much as compilation of java sources for the same project)

- type 'ant docs-install' to put the documentation online on a website

I suspect that, deep down inside, this is what we all want. Rather than
debate every small piece of the puzzle (interesting slang to throw in:
bike shed) and vote on it, I suggest we agree on the big picture, look
at how far we can get implementing it with existing tools, look at what
work is required, do the work in a scratchpad way (ie don't break the
existing process till the new one works), then incremental upgrade.

ie use a normal intelligent software development process flow. You guys
are supposed to know more about that than me.

Until y'all agree to stop arguing about who's to blame, why it didn't
work before, whose tool is 'biggest' (etc etc) I am *not* going to put
much effort in anymore; I have no time or desire to do this all on my
own, if we can't work together it won't happen.

Until that time I *will*, however, throw a -1 at any change I see that
will remove me further from following the process outlined above.

mvg,

- Leo



--
To unsubscribe, e-mail:   <mailto:avalon-dev-unsubscribe@jakarta.apache.org>
For additional commands, e-mail: <mailto:avalon-dev-help@jakarta.apache.org>


Mime
View raw message