Difference between revisions of "Code4Lib Journal WordPress Input Guidelines"

From Code4Lib
Jump to: navigation, search
(WordPress Buttons)
m (Bibliographies/Endnotes)
(98 intermediate revisions by 22 users not shown)
Line 2: Line 2:
  
 
==The WP Admin Interface==
 
==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).
+
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-admin/). If you don't have a WordPress editor login and need one, talk to our web admin (Tom Keays).
 +
 
 +
==Proofs for Authors==
 +
A read-only login that is shared with authors can be found in the 'Administrivia' tab/worksheet of our Google Docs article tracking spreadsheet.
  
 
==Title==
 
==Title==
 
Title, including the subtitle, goes in the "Title" field.
 
Title, including the subtitle, goes in the "Title" field.
 +
 +
Article titles are in Title Case -- all major words capitalized. The title is followed by an abstract, which will be pulled from the excerpt section lower on the post page, and byline of the form "by Author" or "by Author 1, Author 2, and Author 3".
  
 
==Article Content==
 
==Article Content==
The body of the article goes in the "Post" field. The top-level header (<code>&lt;h1&gt;</code>) is used for the title of the post, so start with second-level headers (<code>&lt;h2&gt;</code>) 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.'', <code>&lt;em&gt;</code> for emphasized text, <code>&lt;strong&gt;</code> for strongly emphasized text, <code>&lt;blockquote&gt;</code> when quoting blocks of text. Avoid such monstrosities as <code>&lt;font&gt;</code> and <code>&lt;blink&gt;</code>.
+
The body of the article goes in the "Post" field. Use HTML markup appropriately and semantically, ''e.g.'', <code>&lt;em&gt;</code> for emphasized text, <code>&lt;strong&gt;</code> for strongly emphasized text, <code>&lt;blockquote&gt;</code> when quoting blocks of text. Avoid such monstrosities as <code>&lt;font&gt;</code> and <code>&lt;blink&gt;</code>.
 +
 
 +
===Headings===
 +
The top-level header (<code>&lt;h1&gt;</code>) is used for the title of the post, so start with second-level headers (<code>&lt;h2&gt;</code>) for sections of the article,  
 +
<code>&lt;h3&gt;</code> for sub-sections, <code>&lt;h4&gt;</code> if you need a lower level. <code>&lt;h2&gt;</code> are in "Title Case" -- all words capitalized, short words (the, a, in, up, over, about) should not be. <code>&lt;h3&gt;</code> and <code>&lt;h4&gt;</code> are in "Sentence case" -- only the first word is capitalized.  Any header from second- to sixth-level may be used as appropriate.
  
 
===Pasting from Word===
 
===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.  
+
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
 +
Alternatively, use the [http://www.textfixer.com/html/convert-word-to-html.php Word DOC to HTML converter].
 +
 
 +
===Figures & Tables===
 +
Figures and tables are centered, placed inside a P or DIV with class of "caption".  In general, we bold the figure / table label using the strong tag.
 +
 
 +
For example:
 +
<pre>
 +
<p class = "caption">
 +
<img src = "....">
 +
<strong>Figure X.</strong> How to Caption an Image.
 +
</p>
 +
 
 +
<div class = "caption">
 +
<strong>Table X.</strong> How to Caption a Table.
 +
<table>
 +
<tr>...</tr>
 +
</table>
 +
</div>
 +
</pre>
 +
Captions for figures appear beneath the figure, centered, with "Figure X:" in bold, the descriptive text in sentence case, plain text.
  
 +
Captions for tables and code appear above the table, centered, with "Table X:" in bold, the descriptive text in sentence case, plain text.
  
 
===Images and Attached Content===
 
===Images and Attached Content===
In-line images should be no wider than 500px.
+
In-line images should be no wider than 500px. See above section for captioning and image
  
Two options for images and other attached content/media:
+
'''Uploading files manually'''
# use WordPress uploaded content managing feature, or
+
# 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 [http://groups.google.com/group/c4lj-articles/browse_thread/thread/7d66327ef69c507a/6dceb7d578676334?lnk=gst&q=account+upload#6dceb7d578676334 post] on c4lj-articles).  
+
To upload images or other attached media / files, you will need to upload the content to our ibiblio host site manually.
 +
 
 +
To do that, sftp to login.ibiblio.org.  See the Administrivia tab in the shared "C4LJ Article Tracking" doc for the username and password.  
  
 
Change directory to:
 
Change directory to:
 
/public/vhost/c/c4lj/html/media
 
/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:
+
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. This sort of url will be used in the "<img src>" tag:
http://journal.code4lib.org/media/issue1/smith/imagename.png
+
/media/issue1/smith/imagename.png
  
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.  
+
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. (see below)
  
====Code====
+
'''Uploading media via WordPress'''
  
Put all code in <code>&lt;pre&gt;</code> tags.
+
Before uploading files to WordPress, you will need to change permissions on the directory where you are putting the files.
 +
# Login to c4ljeditor@login.ibiblio.org.  Ask Tom Keays for the password for the c4ljeditor account (or see this [http://groups.google.com/group/c4lj-articles/msg/fad004416f12ac25 post] on c4lj-articles).
 +
# Change the directory to /public/vhost/c/c4lj/html/wp-content/uploads/
 +
# WordPress tries to write the files to /public/vhost/c/c4lj/html/wp-content/uploads/[current year]/[current month].  If the current year or month directory does not yet exist, create them, "mkdir [current year]" or mkdir "[current month]" in the appropriate directory.  Creating the directory while logged in makes the owner and group of the directory c4ljeditor and c4lj respectively.  Wordpress will create the directories as nobody/nobody.
 +
# Change the permissions on the [current month] directory from 755 to 777, "chmod 777 [current month]".
 +
# In the WordPress editor, click the "Add an Image" button.
 +
# Browse to and select your image/file.
 +
# Click the Upload button.
 +
# File in the Alternate text and Caption fields.
 +
# Select the size of the image you want to display in the article.
 +
# Click "Insert into Post".
 +
# On the ibiblio.org server, change the permissions on the current month's directory back to 775, "chmod 775 [current month]"
  
=====Code Highlighting=====
+
==== Video ====
  
If the code is in a supported language, we can do syntax highlighting.  
+
We haven't had too much video, but we just had one (a screencast). The option we used was hosting on archive.org. Upload the video, click on the IA 'pillars' icon on the resulting video on the archive.org page to get an 'iframe' embed code, which works fine in our wordpress html source, and I believe the archive.org infrastructure will take care of translating the video to multiple formats and delivering in the proper format for a given browser. Very convenient.  
  
ibiblio has a PHPS extensionm, so if you an "s" on the end of .php files, e.g.,
+
Include a visible link to the archive.org URL for the individual video page as a caption, so printed or otherwise captured versions of the article will always have that link.
 +
 
 +
You don't need to use archive.org if you or we figure out a better way, it's just one option that worked very conveniently so far.
 +
 
 +
===Code===
 +
 
 +
If code is attached as a file, follow the directions above for attached images, except:
 +
 
 +
* If there is not a folder for the author, create it, according to the guidelines above for images
 +
* Create a subfolder under the author's folder for "code".  Insert code files here
 +
* In the article link to the files using the path format http://path-to-the-server/media/issueNumber/authorname/code/filename (e.g., http://journal.code4lib.org/media/issue1/smith/code/something.pl)
 +
 
 +
ibiblio also has a PHPS extension, so if you an "s" on the end of .php files it will display the code rather than try to interpret the page:
 
   <filename>.phps
 
   <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 <code>&lt;pre&gt;</code> tags. Inside of the <code>&lt;pre&gt;</code> tags, but around your code, include
+
Put all inline code in <code>&lt;pre&gt;</code> tags.
[sourcecode language='langcode']...[/sourcecode]
+
  
Replace <code>langcode</code> with the appropriate code from the following list (if more than one option for a language, any one will work).
+
====Code Highlighting====
 +
If the code is in a supported language, we can do syntax highlighting.  
  
{|
+
Code samples entered as preformatted text, as in the following example, are automagically color highlighted in Wordpress by the [http://wordpress.org/extend/plugins/syntaxhighlighter/ SyntaxHighlighter] plugin:
!Language!!Code
+
|-
+
|C++||cpp, c, c++
+
|-
+
|C#||c#, c-sharp, csharp
+
|-
+
|CSS||css
+
|-
+
|Delphi||delphi, pascal
+
|-
+
|Java||java
+
|-
+
|JavaScript||js, jscript, javascript
+
|-
+
|PHP||php
+
|-
+
|Python||py, python
+
|-
+
|Ruby||rb, ruby, rails, ror
+
|-
+
|SQL||sql
+
|-
+
|VB||vb, vb.net
+
|-
+
|XML/HTML||xml, html, xhtml, xslt
+
|}
+
  
Example:
+
<pre>
&lt;pre&gt;[sourcecode language='css']body {
+
[sourcecode language='php']
    font-size: 0.625em;
+
RAW HTML/PHP/XML/Etc. code goes here; change language (in above line) as needed
    background-color: #0000ff;
+
[/sourcecode]
    color: #ffff00;
+
</pre>
  }[/sourcecode]&lt;/pre&gt;
+
 
 +
If the language parameter is not set, it will default to "text" (no syntax highlighting). Supported languages include <tt>cpp, c, c++, c#, c-sharp, csharp, css, delphi, java, js, jscript, javascript, pascal, php, py, python, rb, ruby, rails, ror, sql, vb, vb.net, xml, html, xhtml, and xslt</tt>. Pretty much everything except <tt>perl</tt>.  For a full list consult: http://en.support.wordpress.com/code/posting-source-code/
 +
 
 +
Note: do not surround code with <tt>&lt;pre&gt;</tt> tags, as the <tt>[sourcecode]</tt> tag itself will generate the necessary HTML.
 +
 
 +
For more subtleties of code formatting, see this gist from editor Péter Király https://gist.github.com/pkiraly/c48193925ad3806c31ef010b58e8600f
 +
 
 +
====Ampersand Issues====
 +
We've had some problems with ampersand handling in the sourcecode sections. If you notice extra amp;s in your article, such as "&amp;amp;amp;" and "&amp;amp;amp;amp;", and you're comfortable using only the HTML editor for article entry, try checking the "Disable the visual editor when writing" box on your profile page in the admin.
  
 
==Abstract==
 
==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.
+
Abstracts should be placed in the Excerpt box, displayed a little ways below the "Post" field. If you do not see the Excerpt box, look under "Screen Options" in the top right of the page.  Selecting the down arrow will display fields to show on the screen.  Make sure that 'Excerpt' is selected.  This will display the Excerpt (abstract) input box on the page.  
 +
 
 +
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.
 
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.
Line 97: Line 136:
  
 
==Bibliographies/Endnotes==
 
==Bibliographies/Endnotes==
We would like to provide COinS information with every appropriate citation that does not have a publically accessible url.  
+
Items in a bibliography should be linked to the resource whenever possible.
* 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.  
+
We would like to provide COinS information with every appropriate citation that does not have a publicly accessible url.  
 +
 
 +
It appears the COinS generator at  http://generator.ocoins.info/ is no longer in service. An alternative is [https://www.zotero.org/download/ Zotero's stand alone citation software].
 +
After creating a citation, simply right click the citation and choose export / format: coins.
 +
* Paste the output provided at the end of the reference in HTML. You will need to delete the line breaks inserted into the output created by the generator for it to work properly.
 
* COinS should really always have an ISSN or ISBN.
 
* 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:
+
* Inside the span tag, put the string "(COinS)" with a link to our coins explanation page. Ie:
  
 
<pre><a href="http://journal.code4lib.org/coins">(COinS)</a></pre>
 
<pre><a href="http://journal.code4lib.org/coins">(COinS)</a></pre>
  
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.
+
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. For an example see the [http://journal.code4lib.org/articles/7922 References section of a published article including coins].
 +
-->
 +
===Endnotes style and HTML coding===
 +
* Endnote number in text: The number is the link which appears in square brackets. Square brackets themselves are not part of the link. HTML coding for the text: '''[<a id="ref1" href="#note1">1</a>]'''
 +
 
 +
* The link should work both ways. So, the endnote will link back to the text. HTML coding for the endnote: '''[<a id="note1" href="#ref1">1</a>]'''
  
 
==Author Information==
 
==Author Information==
Line 111: Line 159:
 
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.
 
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.  
+
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. Italicize the author's name when it is first used (for example, "''Foo Bar'' is a librarian at..."). 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.
+
There is a box beneath the article-editing box with the label "Author(s)". 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, WordPress will use the username of the editor, instead.
  
 
==Categories/Tags==
 
==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.  
+
Posts will have "Uncategorized" checked by default. Uncheck that box, and check the box next to the current issue, which will be a subcategory of "Issues."  Do not check the "Issues" category. We generally do not add tags, except for Conference reviews
  
 
==WordPress Buttons==
 
==WordPress Buttons==
Line 132: Line 180:
 
:Use for not yet complete articles. Only editors can see these.
 
:Use for not yet complete articles. Only editors can see these.
 
;Pending Review
 
;Pending Review
:Absolutely useless to us. Only editors can see these. Don't use this status.
+
: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 [http://groups.google.com/group/c4lj-articles/browse_thread/thread/1231b06c09f1289f post] on c4lj-articles for the login information for the author account (username: author).
 
;Private
 
;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 [http://groups.google.com/group/c4lj-articles/browse_thread/thread/d31f58a145ef877b/1ed35fa6bcd01e86?lnk=gst&q=author+preview#1ed35fa6bcd01e86 post] on c4lj-articles for the login information for the author account.
+
:We don't use this option anymore.
 
;Published
 
;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.
+
: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.
  
[[Category:Code4Lib Journal]]
+
==Publishing an Issue==
  
==Dates of Posts--order on ToC==
+
# Let everyone on the c4lj-articles list know you are getting ready to publish (so they can save and close any open articles).
The dates of the posts in Word Press control what order they will show up in on the issue table of contents.
+
# Log in to WordPress
 +
# Make sure that all articles for the issue have the correct issue category selected and have been set to 'Pending Review'.  Make sure that the "Uncategorized" and "Issues" categories are unchecked (only the specific issue should be selected).
 +
# Sanity check:  count the number of posts which should appear in the publish list
 +
# Click on Posts -> Issues (on the left side)
 +
# Click on "Publish" for the issue you'd like to publish.
 +
## You'll get a list of every "Pending Review" article in that issue. Make sure the number of articles in the list matches your previous count.  Don't see all the articles you think you should see? They could be still in Draft status, or not in the correct Issue category, or still have  "Uncategorized" selected, or someone may still have it in edit mode. Go back to the posts list and make any necessary changes, and start from #5 again.
 +
# Drag and drop the article titles until they're in the order you want. The order you see there is the order you'll see on the home page (and probably the opposite of the order you'll see in your feed reader).
 +
## Note: It's the coordinating editor's responsibility to decide what order he or she would like the articles to show up in, and order them appropriately when publishing the issue. In general, we try to put the articles with the widest appeal first, and special types (columns, special reports, book reviews, etc.) at the end.
 +
# Click on Posts -> Categories (on the left side)
 +
# Make sure all three fields for the current issue are filled in and correct:
 +
## The human-readable name of the issue goes into the Name field -- e.g., "Issue 15".
 +
## The date of publication goes into the Description field -- e.g., "2011-10-31".
 +
## The URL name goes into the Slug field -- e.g., "issue15" would give the URL of the issue, http://journal.code4lib.org/issues/issue15
 +
# Click "Publish Issue" (optionally setting the publication time, first). Setting the time should only have an impact on readers who are not logged into the c4lj site. Editors will be able to see the published articles.
 +
# Go to the Journal front page; check the number of articles is correct (again) and that they are in the right order.  If there is a problem, go back to the admin interface, click on Posts -> Issues and click Unpublish for the issue.  Make whatever corrections are needed and proceed from #5 again.
 +
# Once the issue is finally published, go to [[Code4Lib_Journal_Entries_in_Directory_of_Open_Access_Journals]] and follow the directions to upload the issue metadata to DOAJ.
 +
# Submit URLS to Internet Archives for harvest ([https://gist.github.com/ruthtillman/fa7562989f299e4904c7fb0448d1fc83#file-waybacksubmit-py Wayback Submission Script] )
 +
# Send out announcements (see [[Code4Lib_Journal_Publicity_Venues]])
 +
# Update [http://journal.code4lib.org/editorial-committee#coordinating Coordinating Editor] on the Editorial Committee page to state the name of the editor for the next issue.
  
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.
+
==Corrections==
 +
See [http://groups.google.com/group/c4lj-articles/browse_thread/thread/8eaabcff2d9c000d/a0aeeb9367fcea5f?lnk=gst&q=errata#a0aeeb9367fcea5f|the editors' list] for how to make corrections. Generally, use an Errata or Correction section at the end with information about the change that was made and have the actual text link down to that section. See also [[Code4Lib_Corrections]]
  
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).
+
[[Category:Code4Lib Journal]]
 
+
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?
+

Revision as of 17:12, 23 April 2019

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-admin/). If you don't have a WordPress editor login and need one, talk to our web admin (Tom Keays).

Proofs for Authors

A read-only login that is shared with authors can be found in the 'Administrivia' tab/worksheet of our Google Docs article tracking spreadsheet.

Title

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

Article titles are in Title Case -- all major words capitalized. The title is followed by an abstract, which will be pulled from the excerpt section lower on the post page, and byline of the form "by Author" or "by Author 1, Author 2, and Author 3".

Article Content

The body of the article goes in the "Post" field. 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>.

Headings

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, <h3> for sub-sections, <h4> if you need a lower level. <h2> are in "Title Case" -- all words capitalized, short words (the, a, in, up, over, about) should not be. <h3> and <h4> are in "Sentence case" -- only the first word is capitalized. Any header from second- to sixth-level may be used as appropriate.

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. Alternatively, use the Word DOC to HTML converter.

Figures & Tables

Figures and tables are centered, placed inside a P or DIV with class of "caption". In general, we bold the figure / table label using the strong tag.

For example:

<p class = "caption">
<img src = "....">
<strong>Figure X.</strong> How to Caption an Image. 
</p>

<div class = "caption">
<strong>Table X.</strong> How to Caption a Table. 
<table>
<tr>...</tr>
</table>
</div>

Captions for figures appear beneath the figure, centered, with "Figure X:" in bold, the descriptive text in sentence case, plain text.

Captions for tables and code appear above the table, centered, with "Table X:" in bold, the descriptive text in sentence case, plain text.

Images and Attached Content

In-line images should be no wider than 500px. See above section for captioning and image

Uploading files manually

To upload images or other attached media / files, you will need to upload the content to our ibiblio host site manually.

To do that, sftp to login.ibiblio.org. See the Administrivia tab in the shared "C4LJ Article Tracking" doc for the username and password.

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. This sort of url will be used in the "<img src>" tag: /media/issue1/smith/imagename.png

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. (see below)

Uploading media via WordPress

Before uploading files to WordPress, you will need to change permissions on the directory where you are putting the files.

  1. Login to c4ljeditor@login.ibiblio.org. Ask Tom Keays for the password for the c4ljeditor account (or see this post on c4lj-articles).
  2. Change the directory to /public/vhost/c/c4lj/html/wp-content/uploads/
  3. WordPress tries to write the files to /public/vhost/c/c4lj/html/wp-content/uploads/[current year]/[current month]. If the current year or month directory does not yet exist, create them, "mkdir [current year]" or mkdir "[current month]" in the appropriate directory. Creating the directory while logged in makes the owner and group of the directory c4ljeditor and c4lj respectively. Wordpress will create the directories as nobody/nobody.
  4. Change the permissions on the [current month] directory from 755 to 777, "chmod 777 [current month]".
  5. In the WordPress editor, click the "Add an Image" button.
  6. Browse to and select your image/file.
  7. Click the Upload button.
  8. File in the Alternate text and Caption fields.
  9. Select the size of the image you want to display in the article.
  10. Click "Insert into Post".
  11. On the ibiblio.org server, change the permissions on the current month's directory back to 775, "chmod 775 [current month]"

Video

We haven't had too much video, but we just had one (a screencast). The option we used was hosting on archive.org. Upload the video, click on the IA 'pillars' icon on the resulting video on the archive.org page to get an 'iframe' embed code, which works fine in our wordpress html source, and I believe the archive.org infrastructure will take care of translating the video to multiple formats and delivering in the proper format for a given browser. Very convenient.

Include a visible link to the archive.org URL for the individual video page as a caption, so printed or otherwise captured versions of the article will always have that link.

You don't need to use archive.org if you or we figure out a better way, it's just one option that worked very conveniently so far.

Code

If code is attached as a file, follow the directions above for attached images, except:

ibiblio also has a PHPS extension, so if you an "s" on the end of .php files it will display the code rather than try to interpret the page:

 <filename>.phps

Put all inline code in <pre> tags.

Code Highlighting

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

Code samples entered as preformatted text, as in the following example, are automagically color highlighted in Wordpress by the SyntaxHighlighter plugin:

[sourcecode language='php']
RAW HTML/PHP/XML/Etc. code goes here; change language (in above line) as needed
[/sourcecode]

If the language parameter is not set, it will default to "text" (no syntax highlighting). Supported languages include cpp, c, c++, c#, c-sharp, csharp, css, delphi, java, js, jscript, javascript, pascal, php, py, python, rb, ruby, rails, ror, sql, vb, vb.net, xml, html, xhtml, and xslt. Pretty much everything except perl. For a full list consult: http://en.support.wordpress.com/code/posting-source-code/

Note: do not surround code with <pre> tags, as the [sourcecode] tag itself will generate the necessary HTML.

For more subtleties of code formatting, see this gist from editor Péter Király https://gist.github.com/pkiraly/c48193925ad3806c31ef010b58e8600f

Ampersand Issues

We've had some problems with ampersand handling in the sourcecode sections. If you notice extra amp;s in your article, such as "&amp;amp;" and "&amp;amp;amp;", and you're comfortable using only the HTML editor for article entry, try checking the "Disable the visual editor when writing" box on your profile page in the admin.

Abstract

Abstracts should be placed in the Excerpt box, displayed a little ways below the "Post" field. If you do not see the Excerpt box, look under "Screen Options" in the top right of the page. Selecting the down arrow will display fields to show on the screen. Make sure that 'Excerpt' is selected. This will display the Excerpt (abstract) input box on the page.

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

Items in a bibliography should be linked to the resource whenever possible.

Endnotes style and HTML coding

  • Endnote number in text: The number is the link which appears in square brackets. Square brackets themselves are not part of the link. HTML coding for the text: [<a id="ref1" href="#note1">1</a>]
  • The link should work both ways. So, the endnote will link back to the text. HTML coding for the endnote: [<a id="note1" href="#ref1">1</a>]

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. Italicize the author's name when it is first used (for example, "Foo Bar is a librarian at..."). We do want to have some kind of contact information published (personal web page, email address (obscured if desired), etc.) for each author.

There is a box beneath the article-editing box with the label "Author(s)". 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, WordPress will use the username of the editor, instead.

Categories/Tags

Posts will have "Uncategorized" checked by default. Uncheck that box, and check the box next to the current issue, which will be a subcategory of "Issues." Do not check the "Issues" category. We generally do not add tags, except for Conference reviews

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
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 (username: author).
Private
We don't use this option anymore.
Published
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.

Publishing an Issue

  1. Let everyone on the c4lj-articles list know you are getting ready to publish (so they can save and close any open articles).
  2. Log in to WordPress
  3. Make sure that all articles for the issue have the correct issue category selected and have been set to 'Pending Review'. Make sure that the "Uncategorized" and "Issues" categories are unchecked (only the specific issue should be selected).
  4. Sanity check: count the number of posts which should appear in the publish list
  5. Click on Posts -> Issues (on the left side)
  6. Click on "Publish" for the issue you'd like to publish.
    1. You'll get a list of every "Pending Review" article in that issue. Make sure the number of articles in the list matches your previous count. Don't see all the articles you think you should see? They could be still in Draft status, or not in the correct Issue category, or still have "Uncategorized" selected, or someone may still have it in edit mode. Go back to the posts list and make any necessary changes, and start from #5 again.
  7. Drag and drop the article titles until they're in the order you want. The order you see there is the order you'll see on the home page (and probably the opposite of the order you'll see in your feed reader).
    1. Note: It's the coordinating editor's responsibility to decide what order he or she would like the articles to show up in, and order them appropriately when publishing the issue. In general, we try to put the articles with the widest appeal first, and special types (columns, special reports, book reviews, etc.) at the end.
  8. Click on Posts -> Categories (on the left side)
  9. Make sure all three fields for the current issue are filled in and correct:
    1. The human-readable name of the issue goes into the Name field -- e.g., "Issue 15".
    2. The date of publication goes into the Description field -- e.g., "2011-10-31".
    3. The URL name goes into the Slug field -- e.g., "issue15" would give the URL of the issue, http://journal.code4lib.org/issues/issue15
  10. Click "Publish Issue" (optionally setting the publication time, first). Setting the time should only have an impact on readers who are not logged into the c4lj site. Editors will be able to see the published articles.
  11. Go to the Journal front page; check the number of articles is correct (again) and that they are in the right order. If there is a problem, go back to the admin interface, click on Posts -> Issues and click Unpublish for the issue. Make whatever corrections are needed and proceed from #5 again.
  12. Once the issue is finally published, go to Code4Lib_Journal_Entries_in_Directory_of_Open_Access_Journals and follow the directions to upload the issue metadata to DOAJ.
  13. Submit URLS to Internet Archives for harvest (Wayback Submission Script )
  14. Send out announcements (see Code4Lib_Journal_Publicity_Venues)
  15. Update Coordinating Editor on the Editorial Committee page to state the name of the editor for the next issue.

Corrections

See editors' list for how to make corrections. Generally, use an Errata or Correction section at the end with information about the change that was made and have the actual text link down to that section. See also Code4Lib_Corrections