Remove reference.xml and autogenerate from new separate xml docos

[robe]

I suspect many are aware of this and Olivier is probably working on it, but since the breakup of our reference.xml to its 12 constituent parts, our automated build bot is building documentation against the obsolete reference.xml so all the wonderful changes Paul has been making to the documentation are not seen :).

[colivier]

Yeap the reference,xnml split was not that simple as i initially thought ! It's imply to modify the doc/xsl/* files and the doc/Makefile.in to not use a single reference.xml one as before.

I plan to fix that before the end of the week.

[robe]

I was actually thinking it was simple -- just have as part of the make process reference_* target -> reference.xml (probably would be easier if we named our reference files so they are directory wise alphabetical that way I imagine -- you could come up with a hack to -- pick up all the files that start with reference_ and if we add more we just name them so they are always in alphabetical order the way we want them to appear.

Kevin is already doing that to stitch the new sections we autogenerate using the .xsl files -> to generate -- postgis.xml as I recall.

But heck what do I know. I only work with conceptual models not real code. :)

[colivier]

Well that's not that simple too, that's also was my first try ;)

As we need also to load new entities (and so postgis.xml), and if we do that (use postgis.xml rather than reference_*), we need to modify xsl (at least as long as we cannot define entity in other place than DocBook root node)

[kneufeld]

"Yeap the reference,xnml split was not that simple as i initially thought ! It's imply to modify the doc/xsl/* files and the doc/Makefile.in to not use a single reference.xml one as before. "

I'm a little unclear why you can't do what Regina suggests and add new ENTITY snip-its to postgis.xml that will replace the reference.xml ENTITY. Then, in the Makefile.in, you could create a reference-out.xml that merges all the files together and you can use the single file as before as input to the xsl scripts.

[robe]

I am totally confused. All the xmls seem invalid since they use strange new xml terms not defined so can't stand on their own. Is that what you are talking about Olivier? Where are things like &Z_support; defined?

I was actually thinking we don't use an xml parser to glue reference_postgis.xml together

1) cut out the xml <?xml version="1.0" encoding="UTF-8"?> at top of each document 2) Then I think as Kevin says -- build twice a) reference_postgis.xml (which doesn't have the entity stuff and is just all the reference_* cat together) to go in postgis.xml) b) a reference_forparsing.xml (which is basically entity term header stuff + reference_postgis.xml) --> then this one gets used by xsl to create the special sections. 3) Then complete as usual -- replacing our reference.xml in postgis.xml with the new reference_postgis.xml

Though I guess the xsl could be changed to go thru the full doc, though it may break when dealing with the other stuff. It will definitely have more (useless to it) stuff to go thru if we do that.

[robe]

I was thinking we store the entity definitions in a separate file and we use Kevin's (or I assume Kevin wrote that ) -- sed trick to macro replace some <identifiers go here> with these new items -- that way we can reuse it twice and only define the identifiers once.

So have cat stitched standalone reference_parser.xml that has the identifies stitched in.

Then redo it without the identifiers stitched in -- and include this version in the docs as we have always done.

--- Olivier's NOTE --- Regina,

I am totally confused. All the xmls seem invalid since they use strange new xml terms not defined so can't stand on their own. Is that what you are talking about Olivier? Where are things like &Z_support; defined?

That's the entity stuff

To avoid to have lot of redundant text, we use entities instead. But you're right as i have to revert my postgis.xml commit, entities are no more defined for the moment !

I was actually thinking we don't use an xml parser to glue reference_postgis.xml together

Yeap that's also could be an idea.

But we have also to retrieve the entity stuff from postgis.xml file, so no sure that will be the best/easy way to do

-- Olivier

[colivier]

I commit entities stuff as r4866.

I finally choose to slightly modify xsl files, because:

• XSL changes are in fact really small
• We keep the ability to validate with xmllint --valid postgis.xml without having to play first with doc/Makefile
• I already have met sed portability issue, never met with xsl.

As a consequence gardentest xsl file must now been called with postgis.xml rather than refence.xml file.

I keep the ticket open, till Kevin and Regina are Okay on this solution.

[kneufeld]

It works for me ... the autobuilder has no issues building the docs or the tarball.

Good work Olivier.

[robe]

Looks fine to me too. I see the new entries are showing in "What's new in 1.5"

Great job Olivier. I looked at the way you did it and I like it. I think this will also make it easier to integrate Mateusz suggestion about postgresql comments on types, because now we won't be limited to scanning just references section for postgresql help comments (can expand easily by adding in another chapter in your xsl filter).