The use of admonitions - their scope and definition - was raised as part
of a style bug (Bugzilla 456026) and has developed a life of its own.
Keeping Fedora and Red Hat doc policies in sync is generally considered
A Good Thing, so I'm posting (almost) the complete list of comments here
for further discussion:
Comment #1 <https://bugzilla.redhat.com/show_bug.cgi?id=456026#c1> From
David O'Brien (daobrien(a)redhat.com <mailto:email@example.com>) on
2008-07-20 20:43 EST [reply
Perhaps now would be a good time to <snip> reduce the
number of admonitions (3 is plenty).
Comment #2 <https://bugzilla.redhat.com/show_bug.cgi?id=456026#c2> From
Jeff Fearn (jfearn(a)redhat.com <mailto:firstname.lastname@example.org>) on 2008-07-20
23:29 EST [reply
I agree that 5 is over kill, however since we have a _lot_ of existing content
that uses all 5, it would be a major effort to remove the two we decide to drop.
Since this effort won't be undertaken it will mean we will ship books that use
admonitions not discussed in the Documentation Conventions.
IMHO I think that three should be chose and from hereon the other 2 would not be
used and would, over time, be removed from existing docs. But until that process
is complete all 5 should remain documented in the conventions.
Comment #3 <https://bugzilla.redhat.com/show_bug.cgi?id=456026#c3> From
David O'Brien (daobrien(a)redhat.com <mailto:email@example.com>) on
2008-07-21 00:04 EST [reply
s/<caution>[whatever]</caution>/<warning>[whatever]</warning>/g ? :-)
Yes, agreed, a bit of work involved in the update. Let's do Step 1 and decide on
the 2 to drop and the date for their cessation of use. How about:
- integrate Warning and Caution
- integrate Note and Tip
- decide if we still need Important
Probably a bit of redefinition will be required, and possibly a new bugzilla, as
I seem to have hijacked this one.
Comment #4 <https://bugzilla.redhat.com/show_bug.cgi?id=456026#c4> From
Karsten Wade (kwade(a)redhat.com <mailto:firstname.lastname@example.org>) on 2008-07-21
03:14 EST [reply
Not to keep the hijacking up :), but here is something to add to your new bug
report regarding redefining admonitions.
There *are* differences between a note and a tip. There is a difference between
offering warning and shouting caution.
Take it or leave it, but it is going to make it more difficult to integrate
documentation from/to Fedora if the policies are not in sync. Thus, you might
want to take the discussion to fedora-docs-list. You might find many receptive,
since the GNOME style guide is otherwise respected, and they agree with your
Comment #5 <https://bugzilla.redhat.com/show_bug.cgi?id=456026#c5> From
Jeff Fearn (jfearn(a)redhat.com <mailto:email@example.com>) on 2008-07-21
20:36 EST [reply
I agree with Karsten that it would be a damn fine idea for Red Hat and Fedora
docs to be in sync on this.
David could you either open a new bug or start a thread on the Fedora Docs list
Now let this bug continue on about clarifying the styles :)
IPA Content Author
Red Hat Asia Pacific
"We couldn't care less about comfort. We make you feel good."
Federico Minoli CEO Ducati Motor S.p.A.
Name : Mike Worrall
Location : Kirk Ella, Hull , United Kingdom
Profession : Computer Programmer
Company : Howdens Joinery
Goals in Fedora Project :
To have fun , to contribute and to learn.
Want to write about: Anything really. Interested in kernel stuff,
programming IDEs , graphics packages.
Other stuff i'd like to do:
besides documentation , bug-fixing , a bit of programming & maybe
Historical Qualifications :
English,Maths,History,Physics,Chemistry,Computer studies 'O' Levels
Physics,Chemistry 'A' Levels
HND Computer Studies
PGD Computer Studies
Never worked on any other open source projects. Have done a few projects
at work though. SAP implementation + various bespoke warehouse systems
HND/PGD Computer Studies
Computer Skills: Analysis & Design
Programming : COBOL (stop laughing !)
What makes me an excellent match for this project? - a desire to help
others. I really want to help - in any way - small or big
GPG KEYID 809DB9BF
FINGERPRINT 84C4 E321 9A04 99DA CEE4 F0B3 303C 5EF7 809D B9BF
Hope I haven't missed anything (or put up the wrong info)
For the Alpha and Beta releases, we do a one-page wiki of release notes.
This lets the content be the latest. We also lessen the burden on the
Localization (L10n) project.
The main focus of these notes is for people testing the Alpha release.
It should highlight current known problems, things developers want
tested, and so forth. It is *not* a
don't forget that tech reviewers and bloggers read this, so it does
point at the feature list, etc.
On this page, the opening is a copy and update from F9, with the actual
new content starting in this section:
TASK: Can someone start adding the in-progress features under the
Not all features need to be mentioned, use your judgment.
Beat writers -- you can put in any content that is relevant for your
beat, use your judgment.
Questions? Ask here (preferred), #fedora-docs is always open.
Karsten Wade, Sr. Developer Community Mgr.
Dev Fu : http://developer.redhatmagazine.com
Fedora : http://quaid.fedorapeople.org
gpg key : AD0E0C41
Hi, I'm Jonathan Nalley and I'm in the Greenville area of South Carolina, USA
I'm a Systems Engineer in the Systems Architecture department at
NuVox--a CLEC and other IT-ish services provider
Initially, i'm interested in being a release notes beat writer,
specifically for the
Database servers (if no one else has volunteered for it) and we'll see where it
goes from there. I'm also interested in growing my own writing skills
while becoming involved in the community of a distro i've used and
I've been in the IT industry for about 10 years now and have been
involved in an open source project in the past. I enjoy technical
writing and do so now as a component of my paid job.
Please do not reply directly to this email. All additional
comments should be made in the comments box of this bug report.
Summary: game crashes for no apparent reason
Product: Fedora Documentation
Description of problem:
8kingdoms - fedora 8 - Games
I am using fedora 8 x86_64. I just want to get the developers an error message
that only appeared once when it crashed. It crashes almost every time I play it,
but only once did this error message appear.
"Fatal Error: Promenna zadaneho jemna nenalezena"
I have not received any bugzilla backtraces or anything that I could send you to
assist fixing it. If you could let me know what I need to do to help find the
problem please email me back. I have installed the 8kingdoms debug package, but
to no avail for creating a backtrace.
Version-Release number of selected component (if applicable):
It is random for when it crashes. I don't have a clue as to how to reproduce it
except to just play the game. On any move it could happen. The longer the game
the greater the chance it will crash.
Steps to Reproduce:
The screen blanks, the main fedora window comes up greatly expanded. Sometimes
the mouse quits working, sometimes it doesn't. I reboot the computer and
everything comes back to normal. I can also change screen resolution, not accept
the new changes, and it will return to normal.
Ran the program from a terminal and the return message was:
ERROR in script execution. All defenders should be dead!!
This is the best I can do. I hope this helps.
Configure bugmail: https://bugzilla.redhat.com/userprefs.cgi?tab=email
------- You are receiving this mail because: -------
You are on the CC list for the bug, or are watching someone who is.
:Perhaps this is in the purview of the docs project, maybe not :)
I was just packaging some fonts [1,2] where the licensing of upstream
was uncertain. In one instance, something licensed upstream as OFL was
actually a derived work from a GPL+Exception font. The author of the
OFL font had permission from the original author to do this, however,
didn't make that clear due to limitations of the distribution website
In the other case (same upstream author), there were images from a
museum that he made into a font. It again was unclear whether or not
he had gotten permission to do this (he had).
He viewed my request for clarification, in both instances, as me (and
Fedora) essentially accusing him of being a scumbag thief, which was
quite obviously not the intent - rather the intent was to clear up the
legal status of the fonts to evaluate their suitability for inclusion
in Fedora, a great thing. To add to the misunderstanding, the author
in question is a non-native English speaker.
So the question is whether we can come up with something of a template
for these sorts of things, which can't easily be misconstrued - even
by a non-native speaker, that Fedora as a whole could use to avoid
further misunderstandings of this type? Unfortunately, I don't have
the text of what I sent, since the upstream contact is through a
webform and they reply to the e-mail generated from it.
Hi everybody! I pushed the latest version of publican and publican-fedora in to rawhide today. It's not widely tested so I didn't push them in to F8/9 yet.
Major changes are:
single fop config file, it gets made when the rpm is built.
major HTML & PDF overhaul
many big fixes
Thanks to Brian Forte and Andy Fitzsimon for the help on layout.
Thanks to Joshua Wulf and Brian Forte for the help on updating the Users Guide.
Thanks for everyone who opened bugs, even if I haven't gotten around to fixing them yet :D
Here is the change log for this version:
- Fix PO file name missing from translation status report
- Modify xmlClean to output dummy content for empty files (beta)
- Default SHOW_UNKNOWN tags off
- Make unset entity warnings more obvious
- Make docs use DESKTOP styles
- Fix missing list image in html-single articles
- Commented out debug output in chunking xsl
- QANDA set html and css fix BZ #442674
- Fix kde requires. BZ #443024
- Add default FOP xconf file.
- Added help_internals target.
- Added check for banned tags.
- Added --lang to create_book BZ #444851
- Added package tag BZ #444908
- Added ability to ship $lang/files directories with html/xml payloads BZ #444935
- Hardcoded PDF footnote colour to black BZ #446011
- Set segmentedlist.as.table to 1. BZ #445628
- Force monospace on command
- Switched to FOP 0.95Beta
- Fixed crash bug on files names with parentheses BZ #447659
- Fix loose directory name matching when exluding directiories.
- Added GENERATE_SECTION_TOC_LEVEL to allow section level TOC control. BZ #449720
- Banned inlinegraphic. BZ #448331
- Added Article and Set Templates
- Banned xreflabel and endterm. BZ #452051
- Generate FOP config file and font-metricfiles as build. BZ #451913
- Changed HTML and PDF common brand to more pleasing colors. BZ #442675
- Fixed incorrect PDF colours on Fedora and Common brands. BZ #442988
- Fixed PDF TOC missing Chapter numbers on Sections. BZ #452802
- Fixed spaces being removed between inline tags. BZ #453067
- Changed TOC layout (bold chapters + spacing). BZ #453885
- Changed title spacing, unbolded figure/table titles.
- Fix over size images breaking PDF and HTML layouts
- Add missing make Requires. BZ #454376
- Added call to aspell to spell check.
- Fixed incorrect other credit title in PDF. BZ #454394
- Turned on Hyphenation to split verbatim lines.
- Added code highlighting to CSS and PDF
- Remove trailing '.' from formal para title. BZ #455826
- Restructure CSS for easier maintenance of brands
- Add documentation on publican design philosophy. BZ #456170
- Italicised package tag. BZ #442668
- Updated documentation descriptions of Book_Info.xml tags. BZ #456489 BZ #456488
Jeff Fearn <jfearn(a)redhat.com>
Red Hat, Inc
Eric Christensen (sparks)
Ian Weller (ianweller, et al.)
Paul W. Frields (stickster)
Karsten Wade (quaid)
* Eric will be working with the feature wrangler again upon return to
* Jon Stanley's request for a boilerplate
ACTION: *** PAUL - make a draft, submit to list
* Release Notes update - work continues. Successfully building with
publican at this time. More tooling needed for other modules, and for
conversion from wiki -> DocBook XML.
** Mike McGrath, Ian Weller, and Infrastructure team have been informed
of new python-mwlib, which might do the trick
** poorly-constructed SRPM at:
* Wiki gardening
** Need incentives, possibly metrics tied to web banner to show off
people's hard work
** Something tangible? Schwag prize?
** Luke Macken working on fedora-weekly-metrics module:
ACTION: *** KARSTEN - Garden the WikiGardening page so that new people
can understand it. Revisit and revamp task list as needed.
Paul W. Frields
gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233 5906 ACDB C937 BD11 3717
http://paul.frields.org/ - - http://pfrields.fedorapeople.org/irc.freenode.net: stickster @ #fedora-docs, #fedora-devel, #fredlug
<stickster> Roll call!
<stickster> Sparks: Well heck, it could be just you and me for a little bit.
<stickster> quaid will be back here by about UTC 1915.
<stickster> Sparks: I'll start off with something not on the agenda
--- stickster (n=nnnnnpfr@fedora/stickster) changed topic: Docs Project meeting - https://fedoraproject.org/wiki/DocsProject/Meetings - (non-agenda) Features
<stickster> Sparks: IIRC, I got you together with poelcat for some work on Feature pages
<stickster> Have you looked at the revamping that we did to the policy stuff? https://fedoraproject.org/wiki/Features/Policy
<Sparks> I have not.
<Sparks> I've been on travel last week and this week and I don't foresee coming up for air until later this weekend.
<stickster> Oh wow!
<stickster> Yet you're here anyway -- thanks and sorry
<stickster> I forgot it was two weeks!
* ianweller_afk is floating around the channel and might be here or not
<Sparks> Yeah... Been to DC and to Florida
* stickster ducks the floating head of ianweller_afk
<stickster> Sparks: Well, there's a further refinement to the policy that John will be pushing through FESCo this week
<stickster> It changes the way the queue works
<stickster> Hopefully the result means a less confusing process for everyone
* Sparks needs to read up on this
<stickster> Sparks: Let me see if I can find you a URL
<stickster> Sparks: Hm, just hit me up after this, I'll look later
<stickster> Sparks: Anyway, I'm assuming you're still planning on helping John with some of this work
<Sparks> I am
<stickster> that's all, just a FYI
--- stickster (n=nnnnnpfr@fedora/stickster) changed topic: Docs Project meeting - https://fedoraproject.org/wiki/DocsProject/Meetings - back on agenda!
--- stickster (n=nnnnnpfr@fedora/stickster) changed topic: Docs Project meeting - https://fedoraproject.org/wiki/DocsProject/Meetings - jds2001 request for boilerplate
<stickster> This is a bit silly for me to do this agenda if Sparks is the only one here.
<stickster> It's like me being in a room with one other person, yelling "Is there *anyone* here who will take this action item?"
* Sparks coughs and looks down as if to find something in his bag
<ian_maybeafk> hmm, productive meeting
<stickster> ian_maybeafk: Certainly it's fast.
<stickster> ian_maybeafk: I don't get it.
<stickster> ian_maybeafk: We have the easiest process ever now for getting involved. Everyone complained about DocBook XML. We moved to more wiki.
<stickster> They complained getting a wiki account was too hard. We took that barrier away.
<ian_maybeafk> maybe it's the mediawiki syntax
<ian_maybeafk> i was going to create a mediawiki syntax cheat-shirt
<ian_maybeafk> where all the syntax info is upside down
<ian_maybeafk> (so you can read it)
<ian_maybeafk> maybe a short training video/screencast would help
<stickster> ian_maybeafk: AHA!
<stickster> ian_maybeafk: Now you're talking.
<stickster> ian_maybeafk: I just happen to be well equipped to make such a screencast.
<ian_maybeafk> well well well
<stickster> ian_maybeafk: Sounds like I've got something to work on later today
<ian_maybeafk> of course, we still haven't decided on a wiki organization schema
<ian_maybeafk> which might be an important part of learning docs writing on the wiki
<ian_maybeafk> i'm assuming at this point there's no way we're ever going to completely flatten the wiki and go to complete categorization.
<ian_maybeafk> it seems almost impossible
<stickster> As long as we have a "move" function, I'm more concerned with getting people to actually participate in the wiki gardening.
<stickster> (which topic is coming up later.)
<ian_maybeafk> oh excellent
<stickster> So jds2001 asked us for a boilerplate contact letter for FOSS projects -- one written by someone who was entirely focused on positive outreach, so that the person using the boilerplate doesn't have to edit themselves 10 times over to avoid offending the recipient.
<stickster> I'll draft something and make it available for comment and refiling
<stickster> Release notes status!
--- stickster (n=nnnnnpfr@fedora/stickster) changed topic: Docs Project meeting - https://fedoraproject.org/wiki/DocsProject/Meetings - Release Notes status
<stickster> Has anyone visited the new hosted project site?
<stickster> Hmm, not compelling enough?
<stickster> We now have the release notes in that repo building successfully with publican.
* ian_maybeafk feels bad leaving stickster in a meeting with himself :<
<stickster> There are milestones set up in the Trac repo, but I need help -- mainly asking people to file "tasks" that they see aren't done.
<stickster> ian_maybeafk: I think Sparks is still here
<stickster> Maybe he's still looking for something in his bag. :-)
<stickster> quaid is supposed to be back shortly.
<stickster> Then we can, you know, talk to each other.
* ian_maybeafk goes to check out the magic in the release-notes git repo
<stickster> ian_maybeafk: I wrote some intro pages for how to use it -- keeping in mind that Docs people may not understand git
<stickster> ian_maybeafk: So it's a cookbook approach. If something there looks really wrong to you, I can get you access so you can fix the wording/commands
* Sparks is here... Trying to dodge the weather and reply to thousands of email that are still pending.
<stickster> hee hee
<stickster> Anyway, work is progressing steadily.
<stickster> And with that, we come to quaid's item on wiki gardening status.
<stickster> I've been doing some of this as I go along -- the Feature process was one such victim.
* ian_maybeafk notes his friend is here, so who knows whether i'll be here or not
<stickster> I received an email inside Red Hat from a developer who was having real problems navigating through the tangled morass of PackageMaintainers in the wiki
<stickster> So it would be good to visit those.
<quaid> sorry! network problems but we're on now
<stickster> I think the policy pages we want to stay away from.
<quaid> hi friends
<stickster> Hi quaid
<stickster> It's just you, me, partly Sparks and partly ian_maybeafk
<quaid> is Package* open enough ACLs?
<quaid> or do we get added
<quaid> ok, smooth
<stickster> quaid: It's Packaging* I think which is locked down a bit
<stickster> That's where the policy sits, and that's all pretty well written and complete AFAICT.
<stickster> It's the pages that point in there which are a bit of a mess.
<stickster> This page? https://fedoraproject.org/wiki/PackageMaintainers
<stickster> It's confusing.
<quaid> so just that page
<stickster> And it may not be the only one for developers of its kind
<stickster> crap, clauses out of sequence.
<stickster> And it may not be the only one of its kind for developers
* stickster notes that page contains transcludes/templates for each section
* quaid opens page now that greg is done shoulder surfing
<stickster> How can we kick wiki gardening in the ass?
<stickster> Get people to pitch in?
* stickster thinks we need an incentive.
<quaid> hmm, incentives
<quaid> greg had an idea earlier today ...
<stickster> No, I mean like: prizes for wiki edits.
<quaid> use the Special: page that tracks "hasn't been touched in N time"
<quaid> and put a different, shaded/colored background
<quaid> and maybe a watermark -- a pink page --
<quaid> "if you see a pink page and think it shouldn't be active, then update it, or change it to red so that it needs fixing."
<quaid> something visuual
<quaid> and encourage people all over the place, help by hitting up these pages
<stickster> I think "encourage people all over the place" has been shown at this point to be ineffective.
<stickster> What if we were to offer a real bounty of some sort for this work?
<stickster> How could we create and track such a thing, and reduce the chances of gaming the system through things like whitespace fiddling?
<quaid> start with the usuals and grow?
<quaid> that is
<quaid> make sure we highlight people who are kicking ass
<quaid> with auto tooling
<quaid> maybe a banner that rotates?
<quaid> then ...
<quaid> 1. recognition
<quaid> 2. ???
<quaid> 3. profit!
<stickster> Well, I know it should be quite easy to grab the info.
<quaid> right, there is something already but I forget
<quaid> lmacken hack of somekined?
<quaid> I forget
<stickster> spevack just gave me the tipoff
<lmacken> oh yeah, I've been meaning to add more of those
<lmacken> that repo only has a couple of basic wiki metrics
<lmacken> but eventually i'd like to see it have bugzilla, cvs, bodhi, koji, etc
<quaid> ah, cool
<spevack> lmacken: i've done nothing to help you so far, either. my apologies
<lmacken> spevack: it's cool... I've been engulfed in bodhi stuff recently.
<stickster> lmacken: Don't talk to him. He needs to study.
* spevack is "studying" for the rhce
* lmacken also started a class at boston college this week too
* stickster says, having just pm'd spevack several times in the last hour
<stickster> lmacken: So we were talking about...
* spevack cannot bring himself to care about several topics that are likely to be on the test
<stickster> tying this into an incentive somehow, maybe a banner that publicizes people's ass-kicking on the wiki itself
<stickster> or elsewhere
<spevack> current top 5:
<lmacken> neat. I still would like to see us do that gentoo/suse/etc do in their Weekly news -- having a stats section at the bottom
<spevack> IN YOUR FACE, stickster
<stickster> Bite me spevack
<stickster> I'm gonna SO out-wiki you next week.
* spevack will make every dollar added to the fedora budget pages a separate commit
<spevack> so, that's $300 for $FOO. +1 (commit) +1 (commit)
* stickster sends lmacken to ban spevack from stats
<stickster> oops, s/sends/sends patch to/
<lmacken> see, it's this kind of friendly coopetition that we are trying to create ;)
<stickster> That was two commits to the IRC log, can I count that?
* spevack places a watch on all stickster's pages, and removes one of the spaces between each sentence he types every time he commits
<spevack> stickster: you called down the thunder! now you've got it!
<stickster> Two leaders walk in, only one come out.
* spevack recalls the time him and gdk did the giant sumo wrestling suit thing
<stickster> lmacken: What's the bot account message mean?
<spevack> i think i lost. but i think he cheated.
* spevack goes back to studying... sigh
<lmacken> stickster: normal user accounts can only get at most 500 results from a given query... we need to run that script using a 'bot' account to get more
<lmacken> so those stats are not exactly accurate ;)
<stickster> right, it capped at 500.
<stickster> quaid: So, what's the next action on this?
* quaid done saying howdy to bryan che
<spevack> stickster: did i totally just troll an in-progress meeting?
<stickster> spevack: You did, well done sir.
<spevack> for like 5 minutes?
<quaid> we need a technology owner
* spevack runs in shame
<quaid> who can make sure we are gathering and publishing
<quaid> lmacken: since you are doing this for other stuff
<quaid> lmacken: do you want to prototype a full feed of stats like this from Docs?
<quaid> starting with the wiki pull and push to
<quaid> ... FWN, some page somewhere (fp.org top page?), ...
<quaid> where else?
<spevack> stickster: serious question for you:
<quaid> weekly post to fedorastats.wordpress.com to appear on the planet?
<spevack> i was planning on including metrics as a beat in Fedor aWeekly News
<spevack> but I thought it would be best to wait until we had more than jus twiki edits
<lmacken> quaid: sure, I plan on helping to elaborate the metrics generation stuff.
<spevack> which is why i haven't done it yet.
<spevack> should i continue to hold off, or just do it?
<lmacken> yeah, I think we should wait to have more stats from a few more sources
<stickster> spevack: The only thing that makes me reticent is the fact that we keep showing up in the top 10!
<stickster> spevack: OTOH, we can issue a challenge
<stickster> Beat the FPLs and get a free ____
<stickster> Maybe I should fill in that blank before someone else does.
<spevack> :) i tend to agree with lmacken, which is why I've waited.
<stickster> spevack: All right, but the idea is solid
<spevack> we totally need to buy a fedora contributor a pony
<stickster> lmacken: Agreed on the stats
<stickster> This is sort of a side note to the larger question. Aside from this effort...
<stickster> quaid: What else can we do?
<stickster> quaid: Is there a high-level plan for the wiki gardening?
<stickster> High enough that people know where to start digging now?
<stickster> But low enough that someone can grok it?
<stickster> I find https://fedoraproject.org/wiki/DocsProject/WikiGardening
<stickster> But after the first few subsections, it's not task-oriented enough from the new contributor standpoint.
<stickster> That's better!
<stickster> But how to know how to categorize?
<stickster> We are almost out of time here.
<stickster> quaid: Can you take an item to make the Gardening pages clearer from the new-guy perspective?
<stickster> Simple questions, simple answers
<stickster> I'm working on a few other Docs things at present :-)
<stickster> OK, we need to end this meeting I think
<AndreasR> stickster: no prob.. go on it seems to be funny
<AndreasR> without the pony thing
<spevack> AndreasR: do you want a pony?
<stickster> And with that...
Then get on to this bug and help me get the syntax highlighting package in to Fedora!
I'll try and get a new version of publican built this Friday, I'll post the review
URL so we can get it pushed live asap.