Both <book> and <article> in DocBook support a CDATA attribute called "status". (I.e., <book status="published"> or something like that.) Does this mean we could have XSLT do the work of deciding which stylesheet to use, without having to have a new "make" target? When the work is approved, the author or editor can add this attribute to the top of their doc, and the next build fixes the make. If you want to dream really big like Karsten, then think of that status attribute being manipulated by a XML/XSLT capable shell script that is part of a Larger Automated Process. For example, when the doc is published, it gets branched and the branch gets the status="published" tag, whereas HEAD keeps the default draft.
Is this possible?
On Tue, 2005-11-29 at 20:04 -0500, Paul W. Frields wrote:
Both <book> and <article> in DocBook support a CDATA attribute called "status". (I.e., <book status="published"> or something like that.) Does this mean we could have XSLT do the work of deciding which stylesheet to use, without having to have a new "make" target? When the work is approved, the author or editor can add this attribute to the top of their doc, and the next build fixes the make. If you want to dream really big like Karsten, then think of that status attribute being manipulated by a XML/XSLT capable shell script that is part of a Larger Automated Process. For example, when the doc is published, it gets branched and the branch gets the status="published" tag, whereas HEAD keeps the default draft.
Is this possible?
That's a good idea. Another thought might be to pass in any details by way of environment variables when the doc is made. I do this for some "production-style" xsl ...
$ XSLHTML=some.xsl make
Perhaps something like ...
$ CSS=../common/css/production.css make
... just thinking outloud. This approach would allow for local CSS customization and follows a similar path provided by overloading XSLHTML, XSLHTMLNOCHUNK, XSLPDF, FDPDIR.
Thanks, James
-- fedora-docs-list mailing list fedora-docs-list@redhat.com To unsubscribe: https://www.redhat.com/mailman/listinfo/fedora-docs-list
On Wed, 2005-11-30 at 07:51 -0500, James Laska wrote:
On Tue, 2005-11-29 at 20:04 -0500, Paul W. Frields wrote:
Both <book> and <article> in DocBook support a CDATA attribute called "status". (I.e., <book status="published"> or something like that.) Does this mean we could have XSLT do the work of deciding which stylesheet to use, without having to have a new "make" target? When the work is approved, the author or editor can add this attribute to the top of their doc, and the next build fixes the make. If you want to dream really big like Karsten, then think of that status attribute being manipulated by a XML/XSLT capable shell script that is part of a Larger Automated Process. For example, when the doc is published, it gets branched and the branch gets the status="published" tag, whereas HEAD keeps the default draft.
Is this possible?
That's a good idea. Another thought might be to pass in any details by way of environment variables when the doc is made. I do this for some "production-style" xsl ...
$ XSLHTML=some.xsl make
Perhaps something like ...
$ CSS=../common/css/production.css make
... just thinking outloud. This approach would allow for local CSS customization and follows a similar path provided by overloading XSLHTML, XSLHTMLNOCHUNK, XSLPDF, FDPDIR.
That's a good point too -- Tommy has already made allowances for this in his Makefile.common, so this is do-able as well. I suppose we could do this based on tagging in CVS as well. There's probably several other ways we haven't thought of either. I like any way that doesn't make us have to change a big chunk of the current Makefile.common, or put too many additional "don't forget to..." burdens on the authors/editors/publishers. One way or another somebody's got to mark *something*, it's just a matter of what's the most flexible way to do it.
If I remember correctly, there's an order to how XSL stuff is inherited, right? Like, "whoever's first wins," although it could be the opposite, I'm not sure. That would give a pretty easy solution to using your XSLHTML= method above, I'm thinking, since you could just write the new XSL to include the original stuff and process the "production" instructions in the right order. Am I on the right track with this? Sorry I don't know the formal terms correctly at this point -- if I did it would make my comments more readable, I'm sure. ;-)
On Wed, 2005-11-30 at 08:19 -0500, Paul W. Frields wrote:
If I remember correctly, there's an order to how XSL stuff is inherited, right? Like, "whoever's first wins," although it could be the opposite, I'm not sure.
I think it's the last instruction wins, but I also am not sure. :)
- Karsten
Uttered Karsten Wade kwade@redhat.com, spake thus:
On Wed, 2005-11-30 at 08:19 -0500, Paul W. Frields wrote:
If I remember correctly, there's an order to how XSL stuff is inherited, right? Like, "whoever's first wins," although it could be the opposite, I'm not sure.
I think it's the last instruction wins, but I also am not sure. :)
"Most important" wins. You can only set a xsl:param/ or xsl:variable/ once, no matter how many appearances are made. Importance is determined by the "nesting level" of the instance. For example, assume an XSL include() arrangement like this:
#1 xsl/main-html.xsl #2 /usr/shar/sgml/docbook/xsl-stylesheets/html/docbook.xsl #3 /what/ever/goes/on/in/there.xsl #3 /its/a/mystery/to/me.xsl #3 /tommy/can/you/hear/me.xsl #2 redhat.xsl #2 html-common.xsl
The left column represents the priority of the definitions in a file. The right colum shows the XSL include hierarchy.
So definitions in #1, xsl/main-html.xsl take precedence over any definitions further down the include tree. This is how we can override any foolish settings deep within the DocBook distribution without resorting to rocket surgery on the files...
At a given precedence, first definition wins.
HTH
Uttered "Paul W. Frields" stickster@gmail.com, spake thus:
Both <book> and <article> in DocBook support a CDATA attribute called "status". (I.e., <book status="published"> or something like that.) Does this mean we could have XSLT do the work of deciding which stylesheet to use, without having to have a new "make" target?
Maybe I know this, but I can't remember it at the moment. I need a little more thinking on this. My question is:
When is an FDP document "published"?
It seems to me that being considered as a published document is solely determinable from the context in which the document appears. I'm not considering "publication" as it relates to copyright, just making the distinction between DRAFT and PRODUCTION versions of a doc.
For example, you write a manuscript and send it to a publisher. They love the first draft and fire up the presses. Now, the copy you sent them is clearly DRAFT and their bound version is clearly PRODUCTION, even though the words in each are exactly the same: it's the context or pedigree that matters.
Documents built locally from CVS can never be "production" because they are not official copies. To emphasis this, we now have a watermark indicating its draft status.
Documents obtained from DocsRawHide can never be "production" and need to be watermarked as draft.
Official, production-quality documents are located (where?) and produced by (whom?). Only those copies need have the draft watermarking revoked.
Docs included in the distribution are "production". Where else do the official docs reside? Who places them there? How do they know when to do this?
I don't think the document itself should know whether it is released or not. It is too easy to leave the blessing in the document as modifications are in progress. An external mechanism makes sense to me.
We really need only one CSS stylesheet in the docs CVS: the fedora-draft.css file, and we have that.
Any official-looking document renderings should come from whom ever is constructing the official-looking release, but anything in our CVS is strictly for draft documents.
Does this mean that document authors can't generate official document renderings? Yes, if by that you mean "Fedora Documentation Project" official copies. Anyone wanting to produce their own published renderings are free to take the "fedora-draft.css" stylesheet and edit as desired.
I would agree to change the XSLT and Makefile.common stuff to reference "fedora.css" and to make "fedora.css" a symlink to the "fedora-draft.css" file. That would make switching the CSS stylesheet easier because a change would not corrupt the local CVS image.
Comments? Suggestions? Donations?
On Wed, 2005-11-30 at 11:41 -0600, Tommy Reynolds wrote:
Does this mean that document authors can't generate official document renderings? Yes, if by that you mean "Fedora Documentation Project" official copies. Anyone wanting to produce their own published renderings are free to take the "fedora-draft.css" stylesheet and edit as desired.
I would agree to change the XSLT and Makefile.common stuff to reference "fedora.css" and to make "fedora.css" a symlink to the "fedora-draft.css" file. That would make switching the CSS stylesheet easier because a change would not corrupt the local CVS image.
All sounds great to me! As someone using the fedora/docs-common toolchain for internal process documentation, I would very much like the ability to overload with a custom *production* css. As you suggest, I think it makes sense to not have that information live in the document. I like the XSLHTML and XSLHTMLNOCHUNK environment variable approach because it allows us to keep in sync with fdp docs-common and use our own xsl tweaks when it comes to *production*.
I made a few Makefile.common changes that allow for passing in a CSS env var that points to a css file. That file is then copied over as fedora.css. I would have liked to use ${DOCBASE}.css but I can't figure out how to use variables in the html-common.xsl. I have attached those changes just to show where I was headed.
Thoughts/concerns?
Thanks, James Laska
On Wed, 2005-11-30 at 11:41 -0600, Tommy Reynolds wrote:
Documents built locally from CVS can never be "production" because they are not official copies. To emphasis this, we now have a watermark indicating its draft status.
Documents obtained from DocsRawHide can never be "production" and need to be watermarked as draft.
We really need only one CSS stylesheet in the docs CVS: the fedora-draft.css file, and we have that.
Any official-looking document renderings should come from whom ever is constructing the official-looking release, but anything in our CVS is strictly for draft documents.
I agree. This is in line with the general trademark policy, too (people can freely copy, modify, and then rebrand, but not pass off modified copies as an "official Fedora" product).
On Wed, 2005-11-30 at 11:41 -0600, Tommy Reynolds wrote:
Uttered "Paul W. Frields" stickster@gmail.com, spake thus:
Both <book> and <article> in DocBook support a CDATA attribute called "status". (I.e., <book status="published"> or something like that.) Does this mean we could have XSLT do the work of deciding which stylesheet to use, without having to have a new "make" target?
Maybe I know this, but I can't remember it at the moment. I need a little more thinking on this. My question is:
When is an FDP document "published"?
+1 to all your observations, you are totally on track. Our objective is to:
* Make it an easy, automated process for a document to move to the state of being published. * Restrict who can do that task, so that it is truly formal.
As Paul alluded to, I'm certain we are going to be doing automation on top of this.
Imagine a workbench that writers and editors use, essentially a customized and streamlined CMS built on our systems. On the front side it allows writers to add draft content, work with it in their editor of choice on- or off-line, then push that content to the editors. The editors can approve or deny, and may or may not be allowed to edit. This can then be pushed to publish, or, if flagged for it, pushed to a publisher, who does the final approval.
What is happening on the back side is dependent on what we choose here. This was the basis for my agreeing with Paul's idea in concept. Something that can be done to a module to make it publish, checked in and tagged or branched, and have that publication approval stick to just that tag or branch. Then revert back to a draft status.
The alternative to this is to capture the publish/draft information in a database and work up some metadata about it. That's what traditional CMS does. But we have CVS doing all that for us, why mess with it?
Official, production-quality documents are located (where?) and produced by (whom?). Only those copies need have the draft watermarking revoked.
For now, we need to do it manually. Sorry. We just need to document the process (on the Wiki) and adhere to it.
Docs included in the distribution are "production". Where else do the official docs reside? Who places them there? How do they know when to do this?
Part of our process, and eventually tool, is to put the proper CSS in the packaged documentation.
Do my concepts answer your conceptual questions?
I see this workbench landing in chunks, pieces by quarter ... three months, six months, etc.
I don't think the document itself should know whether it is released or not. It is too easy to leave the blessing in the document as modifications are in progress. An external mechanism makes sense to me.
Is CVS okay for this? That is, the tag or branch has meaning or a specific string (PUB). Wherever you build, check the tag on the file in order to use the for-publish stylesheets.
This would disable off-line builds of for-publish documents, as CVS would be required. That makes the toolchain enforce behavior
We really need only one CSS stylesheet in the docs CVS: the fedora-draft.css file, and we have that.
Any official-looking document renderings should come from whom ever is constructing the official-looking release, but anything in our CVS is strictly for draft documents.
I don't know about moving this to another repository ... how about a 'publish' module with ACLs?
Does this mean that document authors can't generate official document renderings? Yes, if by that you mean "Fedora Documentation Project" official copies. Anyone wanting to produce their own published renderings are free to take the "fedora-draft.css" stylesheet and edit as desired.
Agreed, make it easy for people to comply with the trademark guidelines ... by making it harder for them to use the trademarked material incorrectly. :)
I would agree to change the XSLT and Makefile.common stuff to reference "fedora.css" and to make "fedora.css" a symlink to the "fedora-draft.css" file. That would make switching the CSS stylesheet easier because a change would not corrupt the local CVS image.
+1
Comments? Suggestions? Donations?
Two out of three ain't bad for today.
- Karsten
Uttered Karsten Wade kwade@redhat.com, spake thus:
When is an FDP document "published"?
+1 to all your observations, you are totally on track. Our objective is to:
- Make it an easy, automated process for a document to move to the state
of being published.
- Restrict who can do that task, so that it is truly formal.
As Paul alluded to, I'm certain we are going to be doing automation on top of this.
I hear and obey. Actually, the trouble is getting me to listen ;-)
Using the excellent suggestion made by James Laska yesterday, I've added two more macros to "docs-common/Makefile.common" that give the maker control over the CSS stylesheet selection.
I'll have a more visible email about this composed shortly.
Cheers
-
James Laska -
Karsten Wade -
Paul W. Frields -
Stuart Ellis -
Tommy Reynolds