{RFC] XSLT for draft watermarking?
by Paul W. Frields
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?
--
Paul W. Frields, RHCE http://paul.frields.org/
gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233 5906 ACDB C937 BD11 3717
Fedora Documentation Project: http://fedora.redhat.com/projects/docs/
17 years, 10 months
Docs packaging and Yelp
by Shaun McCance
I'm on fedora-docs-list, but I'm afraid I can't usually manage
to stay current with it. So my apologies for coming back to
this discussion late in the game. I am one of the maintainers
of Yelp, Gnome's help browser.
It's my understanding that Matthias Clasen has patched Yelp
to display some of the Fedora documentation on the front page.
There was a lot of talk in threads on this list about how to
manage things with upstream.
Currently, we have a situation where at least Ubuntu and Fedora
are both patching Yelp in different ways to accomplish the same
thing, which rather sucks. Ubuntu did contact me about this,
but we were unable to work something out in the time-frame they
needed, so they ended up doing their own hack. One reason we
had problems is that I wasn't sure how best to make this work
for all downstream distributors.
Just as a point of reference, in the future, when there's some
question as to how to coordinate things with upstream, you might
consider actually contacting the upstream developers.
I know how Ubuntu changed Yelp. And my understanding is that
Fedora is just putting General|Linux|Distributions|Other on the
front page. I assume this was done by changing scrollkeeper.xml
slightly. Could somebody send me the patch? With a clear idea
of how both Ubuntu and Fedora have done this, we should be able
to produce a better upstream method in 2.14 or 2.16.
// Shaun
17 years, 10 months
Draft document rendering
by Tommy Reynolds
Hi, folks!
We have repeatedly had confusion about the HTML (and PDF?) formatting
produced by our current "css/fedora.css" stylesheet. It is important
to realize that any local rendering has *no official status". In
particular, the Fedora project (or anyone else for that matter) can
and will choose their own stylesheet settings.
To that end, I've changed the default CSS stylesheet from
"fedora.css" to "fedora-draft.css". This new stylesheet uses the
background image "docs-common/images/watermark.png" to place the text
"DRAFT / NOT FOR REFERENCE" diagonally across each HTML page.
Each of you will need to update your "docs-common/" directory to pick
up the new files. There is a new directory "docs-common/images".
You may need to:
$ cd docs-common
$ cvs update -d
to pick up the new directory.
There is also a new shell script "docs-common/bin/use-prod-css" that
will change the CSS file used by the rendered HTML document. At the
moment there is no way to automatically generate the
"production-looking" release. More on that later.
Cheers
17 years, 10 months
Document translation
by Manuel Ospina
Hi,
I have some question regarding the translation of documents:
1. To access the CVS server, do translators need a new ssh-key (and
account) or they can use the same one used to translate packages.
2. Are we still using cvs.fedora.redhat.com:/cvs/docs ?
3. Can individual translators modified the Makefile or they should
report the list?
Cheers,
Manuel
17 years, 10 months
[RFC] Packaging technology update
by Tommy Reynolds
Hello, All!
As part of getting the RPM's built for the Fedora documents, there
are a number of files necessarily that all must be consistent. For
example, there is a revision history within the DocBook document
itself and a similar one for the RPM package. There is an author /
editor / translator list for the DocBook information and a similar
list for the RPM. The list goes on, but you get the idea.
Since I'm lazy and don't want to do the same task twice, I've
developed some XSLT stylesheets that will generate:
1) the <bookinfo> or <articleinfo> information in the DocBook itself;
2) the OMF file needed for the yelp integration;
3) the ".desktop" file needed for the GNOME menu system;
4) the ".spec" file needed for the RPM packaging.
All that is needed is for the authors, translators, and editors to
enter the information once in an "rpm-info.xml" file. Then, the
document build system Makefile.common will be able to automatically
generate the derivative files as needed.
So that you can get an idea of how this will work, I've also added a
sample "rpm-info.xml" file to the Example Tutorial. To see this
work, type the following command from the "example-tutorial/"
directory:
$ xsltproc --stringparam doctype articleinfo \
../docs-common/packaging/bookinfo.xsl rpm-info.txt
When we get this worked out, we will redirect this generated XML into
a file and the base document will include it rather than having the
<articleinfo> stuff hardcoded within it.
As new translations are added to the document, the translator just
adds the new locale to the Makefile ${LANGUAGES} macro and updates
"rpm-info.xml" with the translated document name and description.
Everything else adapts itself to the new information and out comes a
localized RPM package. This is just the plan, we're not quite there
yet, but we're very close.
The rest of this is probably of interest only to KWADE and STICKSTER, but feel
free to read along.
In the "docs-common/packaging" directory are some new files:
rpm-info.dtd -- DTD for the "rpm-info.xml" files
bookinfo.xsl -- XSLT stylesheet to extract the <articleinfo> stuff
desktop.xsl -- XSLT stylesheet to build the "{docbase}.desktop" file
omf.xsl -- XSLT stylesheet to generate the OMF file
spec.xsl -- XSLT stylesheet to generate an RPM ".spec" file
Of these XSLT stylesheets, "spec.xsl" is the most tentative. I'm not
clear about how to structure the multi-language RPM generation yet,
so I've put in some stubs to suggest how this technology could
generate a customized SPEC file on the fly.
Suggestions, praise and criticsm are all welcome!
Cheers
17 years, 10 months
Best tagging practice: multi-key sequences?
by Brad Smith
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
Hello all,
I've come upon another scenario where I'm unsure what the best tagging
practice would be.
In general, if a user is instructed to perform a key combo we use the
keycombo and keycap tags:
Press
<keycombo>
<keycap>Ctrl</keycap>
<keycap>Alt</keycap>
<keycap>Del</keycap>
</keycombo>
to initiate a reboot.
or, in the case of a key sequence, something like:
Press <keycap>Esc</keycap>, <keycap>.</keycap> to recall the
last argument of the last command in <command>bash</command>
When the user is being asked to type in text, we use userinput:
Enter the text <userinput>I like penguins!</userinput> into
text document.
The issue is that we're now marking up documentation that deals with
using vi and things are becoming a bit more ambiguous. What about an
instruction like:
To save and quit, press :wq while in command mode
Technically, since :wq is a set of keypresses, rather than arbitrary
text that the user is entering, it seems that it should be marked up as
<keypress>:</keypress>, <keypress>w</keypress>, <keypress>q</keypress>
...but that is awfully klunky. We've instead been opting for
<userinput>:wq</userinput>
even though that is arguably incorrect.
The FDP docs guide doesn't really address situations like this
(multi-key sequences) directly, so is there an informal standard we
should know about before settling on one or the other?
- --Brad
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.1 (GNU/Linux)
Comment: Using GnuPG with Fedora - http://enigmail.mozdev.org
iD8DBQFDhM8uDvp49DvQ8kcRAh+GAJ9R0hFXizWMNfZj2+5xbQR7duyoYQCfd58G
XNqh9lHZpPUen67vtwEddow=
=im/R
-----END PGP SIGNATURE-----
17 years, 10 months
Advise on Fedora RPM's
by Tommy Reynolds
Hello Paul, kwade, list, et. al.
I've been struggling with FDP RPM's for a couple of weeks and they
are not coming together. I think the reason I'm going round and
round is that I don't have a clear idea of what flavors of RPM's we
need and what files should be in each. Nor where they should go when
installed.
I apologize in advance for these ramblings below, but maybe seeing
them in print will help clarify things. If this doesn't make sense
to you, feel free to skip the rest of this email.
>From what I can glean from kwade's postings, we should have:
1) A development RPM that's just a copy of everything that's in the
CVS tree for a document. I guess this would be the foo.src.rpm
package. Installing this RPM would instantiate the files in
/usr/src/redhat or ~/rpm, I guess.
2) A gnome help package with just the XML files, figures, callouts,
and the like. I guess this would be a foo.noarch.rpm, similar to
the RPM's your Makefile changes produce. Installing this RPM
would populate the /usr/share/fedora/doc tree and drop some
desktop files in place, too.
Generating this RPM would actually explode into separate
foo.en.noarch.rpm or foo.zn_CH.noarch.rpm packages depending on
the ${LANGUAGES} make(1) macro. Or should all translations stay
in a single package with per-locale subdirs?
3) An RPM containing the formatted HTML/PDF content, suitable for
browsing and printing. What could this be called? foo.i386.rpm?
I don't know of a good (standard) place for these files to go at
install time.
I've thought about methods to generate the various RPM components,
such as the .spec files. I found a neat program that lets a shell
script extract arbitrary content from an XML document:
http://xmlstar.sourceforge.net/
and have gotten it working on FC4. Built an RPM for it so we can add
it to Fedora Extras if we decide to keep it. Anyway, using this
program I can write a shell script that will parse the title, author
info and revision data from the XML document itself or from a
separate package description file. Built a DTD for that description
file, too.
I ran an experiment where I used the CVS ChangeLog to derive the RPM
%changelog content, but then realized that the RPM changelog needed
to reflect the RPM-specific changes, not the day-to-day editing for
the document itself. OK, I added the RPM change information (not the
ChangeLog, but manual change data) to the XML package description
file and then parsed that.
However, it then struck me that if we have to keep the RPM
package description info in a separate file and maintain it manually,
then why not just fill out the .spec file directly and have done with
it.
Anyone have a clear enough understanding of what the RPM packaging
should be that they can explain it to a total dunce like me? Perhaps
you could take one of the more complete documents, such as the
release notes, and show me the directory hierarchy produced by
installing each of the RPM types I mentioned above. (Or whatever the
correct complement of RPM's should be.)
If you've gotten this far, I'm impressed ;-) Thanks!
Cheers
17 years, 10 months
CMS use cases
by Karsten Wade
Seth asked for some use cases that show what a content management system
(CMS) can do. I wanted to run them by this group, see what your ideas
are.
What would the CMS do? Manage content for Fedora sites.
fedoraproject.org, primarily.
There are multiple roles:
* Editor - logs into a workbench with entire work queue visible:
- Can approve content or push it back for further writing/edits
- If configured, cannot edit the document, can only push forward or
backward
- Push to publish
- Directly to Web, or enables an autobuild of some kind, or pushes
to a higher level publisher
* Writer
- Write content from scratch or amalgamate
- Can use built-in CMS editing functionality, attach a document of
some kind, or check into CVS and point at that as content submission.
- May modify a work when it is pushed back from an editor.
- Modification of published work generates a new workflow, requiring
the same level of approval as previously
- If configured, may retire or set expiration date for own content.
- When ready, can push own content to editor
* Lead Writer
- As above for Writer, can also be injected into the workflow for a
pre-approval/denial step prior to pushing to Editor.
- Can act upon any content from project they lead as if the sole
writer, that is, can modify into the workflow, set expiration, etc.
* Publisher/Editor-in-chief
- Final approver for sensitive content (legal, special marketing)
- May have ability to directly edit content, depending on usage model.
* Content Manager
- Looks for content to retire or revitalize
- Can immediately retire or set expiration date
- Can dig up old content and push it for a rewrite
- Lands in appropriate writer queue
That's what I've got off the top of my head.
Thanks - Karsten
--
Karsten Wade, RHCE * Sr. Tech Writer * http://people.redhat.com/kwade/
gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41
Content Services Fedora Documentation Project
http://www.redhat.com/docs http://fedoraproject.org/wiki/DocsProject
17 years, 10 months
