Promo/Dot/Drupal

This is a guide primarily for Dot editors. However, when submitting an article via the Dot form or by email you can make the editors' job easier (and get your article published more quickly) by formatting it in the way described under "Dot HTML" below.

Drupal

When you log in as an editor, you can see what is in the queue by visiting:

http://dot.kde.org/admin/content/node

To create a new article choose 'Create Content' from the right hand side panel in the Dot home page.

You always want to create a 'Story' in the page that comes next.

For each article you will see a 'View' tab and an 'Edit' tab (you go straight in to the editor when you create a new story following the steps above).

The editor has the following fields (some need to be expanded before you can see all the options):

• Title (text box)
• Dot Catergories (dropdown list)
• Body (test box)
• Input format (collapsed by default)
  • Filtered HTML radio button
  • Full HTML radio button
• Lanugage (dropdown list)
• Menu settings (tab)
  • Menu link title (text box)
  • Parent item (dropdown list)
  • Weight (dropdown list)
• Authoring Information (tab)
  • Authored by (text box)
  • Authored on (text box)
• Revision Information (tab)
  • Create new revision (check box)
  • Log message (text box)
• Publishing options (tab)
  • Published (check box)
  • Promoted to front page (check box)
  • Sticky at top of lists (check box)
• File attachments (tab)
  • Currently attached files
  • Attach new file (button)
• URL path settings (tab)
  • Automatic alias (check box)
  • Text box to set custon alias
• Comment settings
  • Disabled (radio button)
  • Read only (radio button)
  • Read/write(radio button)

Title

This should be snappy and try and include the main point of the story or something to draw in the reader:

Bad: KDevelop 4.1 Released Good: KDevelop 4.1 Brings Git Integration

Titles should be in title case- i.e. the first letter of all words except cojugations ('and', 'of' etc) are capitalised.

Dot Categories

Try and choose the most appropriate one. This is more of an art than a science.

Body

The article - more on this under the HTML section below

Input Format

Most of the time you'll want to change this to 'Full HTML'. It is always fine to set it to full HTML, but on occasion for very simple articles 'Filtered HTML' might work too. If the article looks wrong when you preview it, you probably forgot to change this.

'Filtered HTML' is default so that people posting comments are limited in what they can do.

Language

Always leave this as 'Language neutral'

Menu Settings

Do not touch anything in here

Authoring information

Put in the author's user name. If the submission came via the Dot form then this is included in the email to the list. Otherwise you can use the Dot search form to search for the user name. You'll see matches as you type.

The time field you normally leave blank, then it is filled in with the time that you submit the whole form. Generally when you publish the article, you want to make this field blank so that it is published with the publication time/date rather than the article creation time/date

Revision Information

We normally don't bother with making separate revisions. However, if you are making major changes that you or someone else might want to revert then tick this box and describe the revision to identify it.

Publishing Options

These are the bits that determine when and how the article becomes public. Ticking 'Published' allows anyone with the correct URL to see the article. It also lets Google and other search engines see the article, so it should not be used until the article is fully published. However, ticking 'Published' does not make the article visible on the Dot front page - 'Promoted to front page' does that. So if someone on the list asks you to 'publish' an article, they mean tick both 'Published' and 'Promoted to front page'

We rarely use 'Sticky at the top of lists'. It is really only used if there is a very big announcement that should stay on top for a few days. Generally in that case we don't publish other articles for a few days, rather than have them appear second or third on the list - so discuss on the mailing list before using this.

File Attachments

Pretty self explanatory. We do not tend to tick any of the 'list' checkboxes. If you upload two files withe the same name, Drupal will append '_0', '_1' etc to the file names.

Tip: if you are using Konqui (with KHTML, not sure about WebKit) then you can type the address to a remote file directly in to the file chooser dialog, rather than having to download it to your system first.

Loose conventions are to use the suffix '-small', '-sml' or '-wee' for smaller versions of larger images when both are uploaded - it makes it immediately obvious which is which if you have 'screenshot1.png' and 'screenshot1-sml.png'.

Images that are going to be floated right or left in the article are typically about 300px wide. Main images that will be centred can be up to 500px wide. Large versions of images that will be linked to can be any size (though there is a 2mb limit on uploads). Practically, there's no point wasting bandwidth with images larger than a typical display size unless there is interesting fine detail, so I often resize large images to about 1000px maximum dimension too.

URL Path Settings

You almost certainly do not want to change this. The only exception would be if you accidentally publish with the wrong date or a typo in the title and want to correct that without breaking incoming links (that are syndicated in RSS, Identi.ca, Facebook etc within a few minutes of publishing). If I remember correctly, this option is only available to administrators.

Comment Settings

No need to change this - always leave it at Read/Write

HTML

Drupal will automate a few things for you. There is no need to use <p> tags (although you can include them and it is sometimes useful if you need to set a custom style - i.e <p style="...">). Drupal will also turn http://example.com into a link and will do the same with email addresses.

Links

So the basic things you need to write the HTML for are links, where you want the link text to be something other than the address, i.e.:

<a href="http://example.com">the link</a>

Note, we try and make the links descriptive, so we would have:

"for more information please see the <a href="http://example.com">Foo project website</a>"

rather than:

"for more information please <a href="http://example.com">click here</a>"

Images

The URL for the images you uploaded are displayed under each upload in the 'File Attachments' tab.

Basic Image Insertion

The basic way of including an image is nested in a floating div like so:

<div style="float: right; padding: 1ex; margin: 1ex; border: 1px solid grey;"><img src="http://dot.kde.org/sites/dot.kde.org/files/imagename.png" /><br />Image caption</div>

To link to a larger version of the image (that you already uploaded) use:

<div style="float: right; padding: 1ex; margin: 1ex; border: 1px solid grey;"><a href="http://dot.kde.org/sites/dot.kde.org/files/largeimagename.png"><img src="http://dot.kde.org/sites/dot.kde.org/files/smallimagename.png" /></a><br />Image caption</div>

Note - in most cases you do not need to specify the size for the div as it scales to the image. However, if you have a long caption it will stretch the div rather than wrap on to multiple lines. In that case you must specify the div width (add 4px to the image width) with something like:

<div style="width: 252px; float: right; padding: 1ex; margin: 1ex; border: 1px solid grey;"><a href="http://dot.kde.org/sites/dot.kde.org/files/largeimagename.png"><img src="http://dot.kde.org/sites/dot.kde.org/files/smallimagename.png" /></a><br />Image caption</div>

You can of course also float images to the left and if there are a lot of images to fit in then it makes sense to use both.

Attach your <div>...</div> to the start of a paragraph where you want the image inserted. Do not separate the image and paragraph with a line break.

Inserting a set of images

This is a fairly recent addition (as far as I know) but useful for a set of images that otherwise would be difficult to position and it is also a bit of a time saver). This allows you to vertically stack a set of images in a single div and group them within one border with one caption. It is useful for screenshots and was used, for example, in the KDE Telepathy Sprint report (foot of page on right hand side).

They are done like so:

<div style="float: right; border: 1px solid grey; padding: 1ex; width: 249px; margin: 1ex"><a href="http://dot.kde.org/sites/dot.kde.org/files/1.jpg"><img src="http://dot.kde.org/sites/dot.kde.org/files/small1b.jpg" /></a><a href="http://dot.kde.org/sites/dot.kde.org/files/2.jpg"><img src="http://dot.kde.org/sites/dot.kde.org/files/small2b.jpg" /></a> <a href="http://dot.kde.org/sites/dot.kde.org/files/3.jpg"><img src="http://dot.kde.org/sites/dot.kde.org/files/small3b.jpg" /></a> <a href="http://dot.kde.org/sites/dot.kde.org/files/4.jpg"><img src="http://dot.kde.org/sites/dot.kde.org/files/small4b.jpg" /></a><br />See a preview of some of the results from the sprint in the screenshots above </div>

The important thing here is that to make the images stack, you must specify the div width (image size plus 4px seems to work)

Inserting a large feature image

Occasionally we want to have a large centred image. The main use case is a group photo from a sprint where a larger image makes it possible to see people more easily. Often, they also have a long caption that is done outside of the image.

These are done like so:

<div style="position: relative; left: 50%; padding: 1ex; margin-left: -231px; width: 464px; border: 1px solid grey"><img src="http://dot.kde.org/sites/dot.kde.org/files/KDETelepathy.jpg" /></a></div>

The points here are that again you center the div by using position:relative, a left position of 50% and a negative left margin equal to half the image width plus 1px while setting the div width to the image width plus 4px (experiment with adjusting these values if it doesn't look quite right).

Recent convention seems to have the captions outside of the image, but there's no real reason why they could not be included with the <br /> tag used for other images.

Headings

The Dot headline uses <h1> already, so begin any subheadings at <h2> and work downwards from there.

Style

Interviews

Our current convention is to name both the interviewer and interviewee in an introduction at the start of the article, making their names bold with <b>Name</b> (you can also misuse <strong> for this).

The questions and answers are then set out like:

<b>Interviewer's name:</b> Interviewers question

<b>Interviewee's name:</b> Interviewees answer

Language

We keep it kind of formal - so we tend to avoid using abbreviations: use "do not" rather than "don't" although that does not matter too much.

We can use jokes and a bit of jargon such as "hacker", but not emoticons.

Common English mistakes

These are some things that non-native (and native) English speakers often confuse and that you need to look out for when editing.

It's or Its

"it's" always means "it is". The posessive is "its".

So these are correct:

"KDE software is great, it's getting better all the time" (however, we would probably prefer "it is" here)

"KDE software is great, its biggest strength is consistency"

T or D endings in the past tense

A common error is "build" rather than "built" (and vice versa). The first in present or future: "he will build, I build, they build, he builds" while the latter is the past "he built it, I built it". I think there are some other ones that are similar, but I forget them at present.