docs November 2005

docs@lists.fedoraproject.org

23 participants
32 discussions

{RFC] XSLT for draft watermarking?
by Paul W. Frields 01 Dec '05

01 Dec '05

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/

5 9

Docs packaging and Yelp
by Shaun McCance 29 Nov '05

29 Nov '05

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

2 2

Minutes of FDSCo Meeting 29 Nov 2005
by Stuart Ellis 29 Nov '05

29 Nov '05

Attending: --------- Karsten Wade (quaid) Tommy Reynolds (megacoder) Paul Frields (stickster) Gavin Henry (G2) Stuart Ellis (elliss) Regrets: -------- Tammy Fox (tcf) - leave of absence Schedule of Tasks: ------------------ http://www.fedoraproject.org/wiki/DocsProject/FedoraDocsSchedule Highlights: ----------- * Tommy: Documents built from CVS will now automatically be marked with a "draft" watermark. For details, see the e-mail to fedora-docs-list: https://www.redhat.com/archives/fedora-docs-list/2005-November/msg00123.html A new make option will be added to build documents for public distribution. * Paul: xmlstarlet has now been added to Fedora Extras for both Fedora Core 3 and Fedora Core 4, to assist packaging work. This tool enables you to perform arbitrary queries against an XML file. To install it: su -c 'yum install xmlstarlet' * Karsten: The SELinux FAQ needs a new maintainer to revise and update it for Fedora Core 5. An e-mail has been sent to fedora-selinux-list: https://www.redhat.com/archives/fedora-selinux-list/2005-November/msg00171.… The current version of the FAQ is here: http://fedora.redhat.com/docs/selinux-faq-fc3/ Full IRC Log: ------------- https://www.redhat.com/archives/fedora-dsco-list/2005-November/msg00021.html -- Stuart Ellis stuart(a)elsn.org Fedora Documentation Project: http://fedora.redhat.com/projects/docs/ GPG key ID: 7098ABEA GPG key fingerprint: 68B0 E291 FB19 C845 E60E 9569 292E E365 7098 ABEA

1 0

Draft document rendering
by Tommy Reynolds 29 Nov '05

29 Nov '05

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

1 0

Document translation
by Manuel Ospina 28 Nov '05

28 Nov '05

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

2 1

[RFC] Packaging technology update
by Tommy Reynolds 27 Nov '05

27 Nov '05

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

2 15

OT: By the way...
by Paul W. Frields 26 Nov '05

26 Nov '05

Happy Thanksgiving to those who celebrate it! And let me heartily recommend brining your turkey before you cook it... you'll thank me after dinner! http://www.foodnetwork.com/food/recipes/recipe/0,1977,FOOD_9936_8389,00.html -- 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/

3 2

Best tagging practice: multi-key sequences?
by Brad Smith 24 Nov '05

24 Nov '05

-----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-----

3 7

Advise on Fedora RPM's
by Tommy Reynolds 22 Nov '05

22 Nov '05

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

4 26

CMS use cases
by Karsten Wade 22 Nov '05

22 Nov '05

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

4 5

2024

2023

2022

2021

2020

2019

2018

2017

2016

2015

2014

2013

2012

2011

2010

2009

2008

2007

2006

2005

2004

2003

2002

docs November 2005