Difference between revisions of "Code4Lib Journal WordPress Input Guidelines"

Revision as of 15:51, 15 September 2008

Please follow the guidelines below when creating or editing Code4Lib Journal articles in WordPress. Enter all articles as "Posts".

The WP Admin Interface

To get to WordPress interface for entering an article, choose 'Site Admin' from the footer of any Journal page, login if necessary, and then choose Write//Write Post from the WP admin menus. (Alternatively, go to http://journal.code4lib.org/wp/wp-admin/). If you don't have a WordPress editor login and need one, talk to our web admin (Jon Brinley).

Title

Title, including the subtitle, goes in the "Title" field.

Article Content

The body of the article goes in the "Post" field. The top-level header (<h1>) is used for the title of the post, so start with second-level headers (<h2>) for sections of the article. Any header from second- to sixth-level may be used as appropriate. Use HTML markup appropriately and semantically, e.g., <em> for emphasized text, <strong> for strongly emphasized text, <blockquote> when quoting blocks of text. Avoid such monstrosities as <font> and <blink>.

Pasting from Word

If you just paste content from Word into WP, it ends up with REALLY BAD html. Fortunately, WP has a built-in feature to help with this. Open the 'advanced toolbar' in editing GUI (right-most link), then click on the paste-from-word icon. This transforms Word's html into really nice pretty html.

Images and Attached Content

In-line images should be no wider than 500px.

Two options for images and other attached content/media:

1. use WordPress uploaded content managing feature, or
2. upload the content to our host manually.

jrochkind found the WordPress content managing feature to be more of a pain than it was worth, so is uploading content manually. To do that, sftp to c4ljeditor@login.ibiblio.org. Ask jrochkind for the password for the c4ljeditor account (or see this post on c4lj-articles).

Change directory to: /public/vhost/c/c4lj/html/media

in there you'll find an "issue1" subdir (or issueX subdir--if you don't, create one or ask for help creating one!). Inside THERE, create a subdir with the last name of the first author, and put all your image and other attached content in there. It will now have this sort of url:

Add to your img src or a href's as desired. You can use this not just for images, but for extended code attachments, etc.

Code

Put all code in <pre> tags.

Code Highlighting

If the code is in a supported language, we can do syntax highlighting.

ibiblio has a PHPS extensionm, so if you an "s" on the end of .php files, e.g.,

 <filename>.phps

it does syntax highlighting for you.

We're still deciding if we like the syntax highlighting, don't feel compelled to make it work if it's not working for you (but please let other editors know what your experience is). To make this work, you still wrap your code in <pre> tags. Inside of the <pre> tags, but around your code, include

[sourcecode language='langcode']...[/sourcecode]

Replace langcode with the appropriate code from the following list (if more than one option for a language, any one will work).

Example:

<pre>[sourcecode language='css']body {
   font-size: 0.625em;
   background-color: #0000ff;
   color: #ffff00;
}[/sourcecode]</pre>

Abstract

While you are editing the article, there is a box labeled "Optional Excerpt" a little ways below the "Post" field. Put the abstract here. Use HTML markup as appropriate. What you put in this field is what will be distributed in our syndication feed and what will appear before the article as the abstract.

Assigned editors are ultimately responsible for a good abstract. Authors aren't always the best at writing good abstracts for their articles, you should probably revise or even write a new one from scratch as necessary, even when the author has provided one. Some of the abstracts for my assigned articles haven't even mentioned what I consider the most significant features of the article.

Since indexes (like EBSCO) may end up indexing abstracts and not full text (and even full text indexes may weigh abstracts more highly), the abstract should probably include any important terms that should 'hit' on the article, such as key technologies or concepts.

I've found that extracting sentences or clauses from the article itself is a good way to build an abstract that will represent the article as the authors intended. The conclusion section is often a good place to look for such key sentences/clauses.

Final abstracts should be passed by the authors for approval.

Bibliographies/Endnotes

We would like to provide COinS information with every appropriate citation that does not have a publically accessible url.

• Recommended COinS generator: http://generator.ocoins.info/
• Another option is to use the WP COinS plugin. Open the Code tab, put the cursor before the citation, and click COinS. Enter the appropriate information. This works so-so for journals, and not at all for books.
• COinS should really always have an ISSN or ISBN.
• Inside the span tag, put the string "(COinS)" with a link to our coins expalantion page. Ie:

<a href="http://journal.code4lib.org/coins">(COinS)</a>

This is so the user without a browser extension will see that something is there she might be interested in, and get an explanation of COinS and how to make use of it.

Author Information

Start off each article with a paragraph stating the name(s) of the author(s). Something simple like "By Jonathan Rochkind". If desired, the author's name can be a link to something appropriate.

End each article with a second-level header that says "About the Author(s)", with class="abouttheauthor" set. Then give a short paragraph about each author. We do want to have some kind of contact information published (personal web page, email address (obscured if desired), etc.) for each author.

Add a custom field to the article called "author" (see the bottom of the "write post" page). Anything you put in this field will be treated as the author of the article. This will show up in the ToC and in the syndication feeds. If you don't populate this field, then there will be no author information attached to the article.

Categories/Tags

Every article in issue 1 should be put in a category "Issue 1". Etc. This should make it easier to generate issue specific RSS feeds and do other stuff at a later date.

WordPress Buttons

Save

Saves the article, sets the post status to whatever option is selected in the Publish Status form.

Publish

Saves the article, sets the post status to Pending Review and assigns a timestamp to the article.

If an issue is not yet published, setting the post status to "Published" or clicking the "Publish" button will set the article to "Pending Review" status. If the issue is already published, this would actually publish the article.

WordPress Post Status

An article has four possible statuses. However, only the first three statuses are available to editors.

Draft

Use for not yet complete articles. Only editors can see these.

Pending Review

Absolutely useless to us. Only editors can see these. Don't use this status.

Private

Use for sharing the article with authors. Editors and anyone logged in with user ID 17 (i.e., the author account) can see these. See this post on c4lj-articles for the login information for the author account.

Published

Editors can't see this option. A published post is visible to everyone. It is part of the RSS feed. If you're editing an already published post, don't select anything in the post status form, just hit Save.

Dates of Posts--order on ToC

The dates of the posts in Word Press control what order they will show up in on the issue table of contents.

I think it's the coordinating editor's responsibility to decide what order he or she would like them to show up in, and set the dates appropriately. For issue 1, I did this by setting them all to the same date, and mucking with the actual hour/minute/second time to control order. The most 'recent' (ie, the latest) time will show up first.

I also made a mistake with issue 1 though, thinking the date didn't really matter except for this. In fact, the date/time should be set as close to the actual publication (that is, making public) time as reasonably possible to keep feed readers from getting confused. When I had the date of the post set to a few days before the actual make-public time, this caused the code4lib planet feedreader to put the posts down at the bottom of it's screen the first time they showed up in the feed, since it was ordering by date (reversed).

So coordinating editor should probably set the date/hour to be close to date of actual publication, and then mess with minutes to determine order on ToC?