Latest revision as of 07:34, 31 August 2020

This is a guide primarily for Dot editors (it could also be useful for contributors, but I think it would be better to include a shortened version on formatting in the Dot submission page).

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 may only be available to administrators)

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 conjunctives, articles and prepositions ('and', 'a', 'the', 'of' etc) are capitalised. So:

"KDevelop 4.1 Brings Git Integration and Better PHP Support"

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. What you have to enter is more or less normal HTML, although Drupal can automate a few things for you.

Summary and main text

In some browsers, you see two boxes, one for the summary and one for the main text. In others (Konqueror with KHTML) you only see one. The boxes allow you to write a summary text for the front page and a main text shown on the article page. There is a check box to choose whether the summary is shown in the main view. If you check this (checked by default) then you only need to type the introductory paragraph once. If you want the front page text to not be the same as the start of the main text then uncheck this box.

For browsers that do not show the two boxes, you can define the split for what ends up on the front page by typing:

Generally, we dont' do a separate front page text as often the first paragraph of the main text serves the purpose. If you use a browser that only shows one box and don't type in the  manually then Drupal tries to guess the right point - sometimes it works, sometimes it doesn't.

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

Save and Preview Buttons

'Save' submits you changes. 'Preview' shows you what text/images will be on the Dot front page and the main page - but note that it doesn't save your changes. It is always worth checking thr 'Preview' before you finally publish to be sure what is going to the front page makes sense.

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.

Creative Commons license

KDE content is licensed under Creative Commons Attribution 3.0 Unported License (CC-BY).

This license lets others distribute, remix, tweak, and build upon your work, even commercially, as long as they credit you for the original creation. This is the most accommodating of licenses offered. Recommended for maximum dissemination and use of licensed materials.

This license information is applied automatically in the footnote as part of the Dot structure.

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

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

Upload images and photos to dot.kde.org using the "Add a new file" section of the edit page. KDE content is licensed under Creative Commons Attribution 3.0 Unported License (CC-BY). The license information is added automatically in the footnote section.

Do not link to other image/photo sharing websites. Some of the more popular sites do not respect open licenses, and are known to assume ownership, while restricting access to the original contributor. News sites rely on our open licenses to publish (re-publish) our stories. The use of third party sharing sites compromises this capability. In some cases, news sites have rejected Dot stories on this basis.
Do not link to other image/photo sharing websites.

Image hosting websites frequently disappear after a few years or change the URLs to get to an image. The Dot is a record of the history of KDE and losing the images from the stories spoils them. Ensuring that we host them on KDE infrastructure is a simple way of avoiding this.

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

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

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

<figure 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" width="X" height="Y" /></a><br /><figcaption>Image caption</figcaption></figure>

Note - in most cases you do not need to specify the size for the figure 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 figure width (add 4px to the image width) with something like:

<figure 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 /><figcaption>Image caption</figcaption></figure>

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 <figure>...</figure> 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 figure 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:

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

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:

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 2px 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.

Videos

Todo. Should also include a mechanism to link to the video in a free format

Here is a basic example:

<div style="float: right; padding: 1ex; margin: 1ex; border: 1px solid grey; width: 480px;"><embed src="http://blip.tv/play/AYK_lHoA" type="application/x-shockwave-flash" width="480" height="300" allowscriptaccess="always" allowfullscreen="true"></embed><br />Krita Training DVD Trailer (<a href="http://blip.tv/file/get/Krita-CreatingComicsWithKritaPreTrailer537.webm">Download in WebM format</a> )</div>

Headings

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

Lists

We use standard HTML lists. Either ordered (with numbers):

Or unordered (dot default is square bullets):