Gentoo Weekly News guide

1.  Introduction

The GWN manifesto

The Gentoo Weekly Newsletter (GWN) was founded in December 2002 with the purpose of reporting news from the Gentoo project, and to provide a two-way communication conduit between the developers and the Gentoo community.

As an official PR subproject, the GWN has two main roles to fulfill. It's a propaganda instrument with the aim of promoting Gentoo as a whole, by forming a public image of a highly dynamic, technologically advanced, ambitious project. The second role, equally important, is its community-building aspect, by making Gentoo accessible to users, transparent in its movements, and eventually attractive enough to facilitate the recruiting of new developers.

While being an official publication, the GWN doesn't necessarily reflect opinions of the Gentoo Foundation trustees, or the Gentoo Council, or a majority of developers, or any other steering committee. It's an independent voice within the boundary of its voluntary adherence to the Gentoo Social Contract and the ethics of journalism.

The GWN is written by Gentoo developers, users, amateurs or sometimes even external authors not affiliated with Gentoo in any way other than by submitting an article to the GWN. The editor is responsible for keeping contributions within the guidelines, and looks after ethical and/or legal implications. The newsletter is published under the same Creative Commons license as the documentation on the website.

Best practices

There never was much in terms of rules set forth by the editors of the GWN. The GWN authors have always based their contributions on implicit understanding rather than explicit editorial guidelines. However, some of the best practices that have proven their usefulness can be summarized in a few bullet points:

• The GWN has been published in American English since its first issue. Purely for consistency reasons, we continue to write "favorite" rather than "favourite", prefer to "organize" and not "organise" things, and would probably call a "jumper" a "sweater."
• Punctuation also follows American typography rules. Readers outside the US may not feel entirely comfortable with a period to the left of an end-of-quotation mark, but that's how it's done in American English, even when it's only a single word that's being quoted.
• "Gentoo" is a generic term to be used in a number of combinations. As of itself, it's encompassing everything that's being done in and around the project, and can be used to refer to the "Gentoo community," the "Gentoo subprojects," the "Gentoo fan clubs," the "Gentoo metadistribution," the "Gentoo way of life." Then we have distinct projects that take a name of their own, like the legal bodies and a few tangible or political manifestations, e.g. Gentoo {Linux|*BSD|for Mac OS X} etc., Gentoo {Foundation|Inc.} or Gentoo {Forums|Council}. Only those proper names are capitalized.
• Speaking of which, capitalization inside headlines is generally frowned upon. We Don't Do That.
• Pictures need to be related to the article they appear inside. Their size is limited to 600x450 pixels and a maximum of 100KB. If the copyright of an image lies not with the Gentoo Foundation, a note naming the photographer or the copyright holder is added below.
• ISO standards are followed wherever we can, including currencies ("USD" rather than "dollars" or "$", "JPY" not "Yen" and so on), dates are always written in day (numerical), month (spelt out), year (numerical) order: "12 November 2005," not "11/12/05" or "Nov 12, 2005."
• Names are always given in first name, last name order. This includes Japanese, Korean or Chinese names.

2.  The GWN sections

First section: main Gentoo news

The top section of each GWN contains news contributions from inside the entire Gentoo project. This includes status updates from projects and subprojects, release information, important changes to the Portage tree, infrastructure heads-ups, Gentoo-related news from sponsors, reports from major public events like international trade fairs and developer conferences - in essence a wide variety of things of significant importance to readers.

Contributions to this chapter are often sensitive in nature, sufficient time before publication should be allowed for, in order to cross-check information with Gentoo developers directly involved.

A special case of main news items are the project updates to be submitted by the project leads. Sending a weekly reminder to the various project leads asking for an update (if available) helps assuring input for this category.

If need be, errata and corrections to items in earlier GWNs are appended to the end of the main section, regardless of which chapter they've actually occurred in.

Once finalized, all information should be bundled in XML excerpts following the syntax described in GWN XML Syntax.

These snippets of XML code should be concatenated and sent to gentoo-gwn-admin@gentoo.org (let us assume with the name news.xml).

Second section: feature rotation

The second section is designed to rotate through different categories, including: developer portraits (dev of the week), user stories and interviews (practical application of Gentoo in external projects, companies etc.), and the "Future zone" that deals with Gentoo-related development not entirely fit for release yet, but interesting enough to receive advance coverage:

• Future zone - New developments inside existing projects and entirely new projects alike can brag about what they're currently doing, and where their efforts will eventually lead. The Future zone is not limited to projects entirely governed by Gentoo developers, we occasionally open this space to outside development -- provided it shows sufficient relevance for Gentoo, or at least a promise to end up in the Portage tree at some point.
• Developer of the week - A standardized questionnaire is sent to developers who agree to be portrayed in this section. The monography is compiled from their answers and additional information at the discretion of the author. A photo is added at the top.
• User stories - Often contributed by people who use Gentoo professionally in a corporation or campus, this feature finds unusually interesting applications of Gentoo and exposes them to the public.
• Interviews - Same as above, except that it's conducted as a written interview. Answering questions is often easier for a busy CTO than writing a whole article all by him- or herself. A note at the top explains who is answering, the questions are marked by emphasizing them ("Who are you?", see GWN XML Syntax for details)

All of these categories have in common that they go into much detail about a single topic, either portraying an individual or describing a project or product. They don't carry an explicit limit to their length, but in general shouldn't exceed a third of the entire length of the GWN.

Third section: "Heard in the community"

There are various community sources. To distinguish them we use the following construction:

<section>
<title>Community Source</title>
<body>

<p><b>Title of community information 1</b></p>

<p>
Summary
</p>

<ul>
  <li><uri link="location of source"<Name/Title of referenced source</uri></li>
</ul>

<p><b>Title of community information 2</b><p>
...

</body>
</section>

This construct should be repeated for every source. Possible sources are (just to name a few - more are always better):

• Web Forums - http://forums.gentoo.org
• gentoo-devel - archive
• gentoo-user - archive
• gentoo-server - archive
• alt.os.linux.gentoo - archive
• Planet Gentoo - Planet

For each of those sources, no more than three items per week should get coverage in this section. The main purpose of this section is to point readers to possible sources of community information, not duplication of content. If several threads are dealing with the same topic, they can be appended to a common abstract, with links to Howtos or additional information from different sources if appropriate. Coverage per item should fit in a few lines and link to either a Forum or mailing list thread, the newsgroup via Google groups, or archived blog entries (permanent links only, please).

The combined information (for instance community.xml) should be sent to gentoo-gwn-admin@gentoo.org).

Fourth section: Gentoo international

Gentoo international gets news from around the globe, mostly regional activities of Gentoo user groups, but also limited releases of Gentoo-related products, for example, like a South-African web hoster switching to Gentoo on their server farm etc. To prevent any misunderstanding: US activities belong here, too. International news should be written as if it was generic news, it only needs to be bundled in a different file (for instance international.xml).

Titles are standardized to the extent that they start with the name of the country and a colon, e.g. "Canada: " followed by the actual headline:

<title>Italy: Catalyst conference in Milano</title>

Again, international.xml should be sent to gentoo-gwn-admin@gentoo.org.

Fifth section: Gentoo in the press

The press clippings section gathers references to Gentoo being mentioned in other media. This includes newspapers and magazines, but also books, radio and TV coverage, PR websites that carry Gentoo-related press releases. Some sites are deliberately avoided, like Slashdot threads that only get coverage here when there's an original debate about Gentoo, not just Gentoo mentioned five times in comments on some thread. Others are treated with a certain predilection, like Distrowatch articles about Gentoo and its spin-offs, for example.

Titles have the name of the media followed by the published date in brackets. For every non-English publication (there's no limit to languages used in the press clippings) the language is added in the title, right after the publication date.

<title>Diario del Gentooista (12 November 2005, in Spanish)</title>

The abstract always quotes a couple of ideas from the article, but it's also supposed to put things into perspective for readers with a stronger Gentoo affiliation than the average public. If an article (or video or any other trace) is available on the Internet, a link should be included in the abstract, not in the title. Sites that require registration before allowing access to the content that's referenced here should best be avoided altogether, or, if that's impossible, clearly marked as such.

Tips and Tricks

Tips and tricks can be constructed using regular sections (see GWN XML Syntax). Send the tips to gentoo-gwn-admin@gentoo.org in a single file (tips.xml).

Moves, Adds, and Changes

The following XML construction should be used:

<section>
<title>Moves</title>
<body>

<p>
The following developers recently left the Gentoo team:
</p>

<ul>
  <li>Some developer, or <e>None this week</e></li>
</ul>

</body>
</section>

Repeat for Adds and Changes and change accordingly.

The result should be combined and sent to gentoo-gwn-admin@gentoo.org (teamchanges.xml).

Gentoo security

The glsa2gwn.py script should be used to create the necessary sections for the GLSAs. Just run the following command for each GLSA issued in the last week:

$ glsa2gwn.py /path/to/some/glsa.xml >> security.xml

Then send security.xml to gentoo-gwn-admin@gentoo.org.

Bugzilla

The bug statistics section of the GWN is entirely driven by a script called bugs2gwn.py. Written by AJ Armstrong and modified only slightly since its initial version, it dumps various information directly from bugs.gentoo.org, performs calculations over a seven day period and concatenates the output for use in the GWN. Run the script:

# bugs2gwn.py > bugsYYYYMMDD.xml

and send the resulting file to gentoo-gwn-admin@gentoo.org.

3.  Creating the GWN

Combining all chapters

This is the job of the editor. Make sure you have all the appropriate files that were sent to gentoo-gwn-admin@gentoo.org in your vicinity -- you'll need them.

We start off with a template for the GWN. Copy it to YYYYMMDD-newsletter.xml with of course YYYYMMDD the release date of the GWN. The file is commented heavily, but I'll give an overview for completeness sake:

• Fill in the release date under subtitle
• Fill in the appropriate authors for this week's GWN.
• Fill in the abstract of the GWN. If you need an example, check the news items on Gentoo's main page
• Increase the volume/issue inside version
• Set the release date in date, the correct format is yyyy-mm-dd.
• Include the various files sent to gentoo-gwn-admin@gentoo.org
• Double-check the list of available translations

Verifying the GWN

Store the file inside your testing ground. At the same time, store the image of the developer (of the "Featured Developer of the Week") inside gwn/images/gwn.

Now verify and test your GWN edition.

Proofreading the GWN

Time permitting, you should always send a draft of the upcoming issue to two mailing lists, gentoo-gwn-admin@gentoo.org and gentoo-core@gentoo.org. Try to aim for a time of day when sufficient numbers of native English speakers are available, six to eight hours ahead of publication are good practice, albeit seldom practical. Proofreaders aren't bound to any particular format, they can send fully-fledged patches, sed style "s/foo/bar" sniplets or other corrections to the text.

Publishing the GWN

The publication date of the GWN is set to 0:00 UTC on Monday of each week. Try to conform to this as much as possible, there are automatic scripts in the wild that trigger on the GWN's publication, for example to reference the new issue in other media. If the deadline is missed by too much of a delay, we risk dropping out of those backtracks.

Publishing the GWN is done in steps. First, create the text version of the GWN. A script called gwnproc.py is used for this, with a separate xsl file that provides the formatting for plain text output.

$ gwnproc.py YYYYMMDD-newsletter.xml > YYYYMMDD-newsletter.txt

Edit the resulting YYYYMMDD-newsletter.txt file so that it reads fluently. Pay attention to the links in the Bugzilla statistics section, the script folds lines after 75 characters, which is a nuisance to mail clients if you don't put those links back on a single line.

Next, commit the image(s) and the GWN files to CVS:

(The image(s))
$ cp gwn/images/gwn/YYYYMMDD-nickname.jpg cvs/gentoo/xml/images/gwn
$ cd cvs/gentoo/xml/images/gwn
$ cvs -ko add YYYYMMDD-nickname.jpg
$ cvs commit -m 'Image of nickname' YYYYMMDD-nickname.jpg
$ cd

The GWN overview page references the current issue of the GWN separately. You need to duplicate the YYYYMMDD-newsletter.xml file as current.xml and submit both to CVS.

$ cp gwn/YYYYMMDD-newsletter.xml cvs/gentoo/xml/htdocs/news/en/gwn
$ cd cvs/gentoo/xml/htdocs/news/en/gwn
$ cvs add YYYYMMDD-newsletter.xml
$ cp YYYYMMDD-newsletter.xml current.xml
$ cvs commit -m 'GWN release for YYYYMMDD' YYYYMMDD-newsletter.*

Add an entry for the current issue to the GWN overview file, gwn.xml in the same directory. This is a list of the main news items inside the newsletter conforming to the format found in the table, and very important because the RSS feed uses this entry as its title.

$ vi cvs/gentoo/xml/htdocs/news/en/gwn
Edit the table and add an entry for the current issue
$ cd cvs/gentoo/xml/htdocs/news/en/gwn
$ cvs commit -m 'GWN overview updated' gwn.xml

Write a news item for this week's GWN. You can use this template. Rename to YYYYMMDD-gwn.xml, edit and then commit it to CVS to publish it online:

$ cp gwn/template-news.txt cvs/gentoo/xml/htdocs/news/YYYYMMDD-gwn.xml
$ cd cvs/gentoo/xml/htdocs/news
$ cvs add YYYYMMDD-gwn.xml
$ cvs commit -m 'GWN YYYYMMDD is available' YYYYMMDD-news.xml
$ cd

After committing all xml files and images to CVS, the synchronization to the web mirrors takes up to one hour. You should wait for this to happen before sending out the plain text version of the current GWN through the gentoo-gwn@gentoo.org mailing list. Open your favorite mail client and put the text inside the body of your e-mail. Subject it with the appropriate date (modeled after this: "Gentoo Weekly Newsletter 12 November 2005") and send it out. The mailing list is moderated, so you need to reply to the moderation request it sends to you before the GWN is finally dispatched to the list's subscribers.

Congratulations; you have now successfully released a GWN :)

4.  GWN XML Syntax

Single sections

Single sections, such as used by news items, should be constructed like this:

<section>
<title>Title of the News Item</title>
<body>

<p>
One paragraph.
</p>

<p>
Multiple paragraphs are of course encouraged :)
</p>

</body>
</section>

Inside <p> constructs one can use:

• <e>...</e> for emphasised text
• <c>...</c> for commands users can type
• <b>...</b> for bold text
• <uri link="http://www.gentoo.org">some link</uri> for some link
• <mail link="some@address.com">name of person</mail> is used for e-mail addresses

Apart from <p> one can also use lists like the above. This is accomplished through <ul> (unnumbered) or <ol> (numbered) constructs:

<ul>
  <li>
    Inline text like with <p> constructs
  </li>
  <li>
    Another bullet
  </li>
</ul>

Using code listings

A code listing can be put wherever one would be able to place <p> constructions - not inside them!. Code listings provide no word wrapping - if you place everything on a single line the result will be a document that forces the user to scroll horizontally!

Inside a code listing, the following XML constructs are allowed:

• <comment>...</comment> color the text in red
• <i>...</i> color the text in blue (used for commands)

A code listing is created with the <pre> tag:

<pre caption="Example pre">
# <i>some command</i>
</pre>

Adding illustrations to articles

Pictures (only .jpg or .png, please) accompany articles or interview according to the following syntax. Again, <figure> constructs can be put wherever one would be able to place <p> constructions.

<figure link="/images/gwn/YYYYMMDD_nickname.jpg"
        short="Full Name"
	caption="Full Name" />

The naming convention for images in the GWN is YYYYMMDD_name.jpg (or .png) with YYYYMMDD the year-month-day of the GWN release and name a single word best describing the picture, i.e. the nickname of a developer, a trade fair acronym etc.

5.  Testing Ground

Preparation

Create a directory ~/gwn. Inside that directory, create the dtd/, css/, xsl/ and /images directories.

$ mkdir -p gwn/css gwn/dtd gwn/xsl gwn/images/gwn

Execute the following downloading instructions to download the specific XSL file, DTD, CSS and images:

$ wget -P gwn/dtd/ http://www.gentoo.org/dtd/guide.dtd
$ wget -P gwn/css/ http://www.gentoo.org/css/main.css
$ wget -P gwn/images/  http://www.gentoo.org/images/gbot-s.gif \
  http://www.gentoo.org/images/gridtest.gif \
  http://www.gentoo.org/images/gtop-s.jpg \
  http://www.gentoo.org/images/line.gif \
  http://www.gentoo.org/images/netraverse-gentoo.gif
$ wget -P gwn/xsl/ http://dev.gentoo.org/~swift/local/guide.xsl

Now edit /etc/xml/catalog on your system and add the following line:

<rewriteURI uriStartString="/dtd" rewritePrefix="/home/you/gwn/dtd"/>

Of course make sure that the rewritePrefix points to your created gwn/dtd directory.

Testing a GWN

To test a GWN, we first verify it's XML accuracy. Go to the gwn/ directory and run:

$ xmllint --valid --noout YYYYMMDD-newsletter.xml

If the xmllint application gives no output, your GWN is fine. To view the result of the XML, run xsltproc:

$ xsltproc xsl/guide.xsl YYYYMMDD-newsletter.xml > test.html

Point your browser to the gwn/test.html file on your disk - it should render the GWN correctly.

6.  CVS Information

Setting up your CVS account and such is beyond the scope of this document. Contact the infrastructure team if your CVS access gives you problems.

To get the right CVS module on your disk, issue the following commands:

$ mkdir cvs
$ cd cvs
$ export CVSROOT=yournick@cvs.gentoo.org:/var/cvsroot
$ cvs co gentoo