Managing electronic references

Technical writers largely belong to a group fondly called perfectionists. Their contributions ideally are well-crafted, poignant, and comprehensible in terms of content and aim to awaken some curiosity within the minds of readers. However, without good research, nothing else matters.

Various software tools have been designed to keep authors from getting bogged down in a sea of references and to help them give credit where credit is due. In this article, I will take a look at what these tools provide and how successful they are.

One rule you must adhere to as a writer is: Credit your sources. Correct referencing is of great importance. References are made up of metadata that includes the author, title, publisher, location, and date of publication, and in the case of online material, the date and time of access.

The form of citations and references used depends on the subject matter, publisher, and common practices (see the "Reference Versions and Formats" box to see how it's done at Linux New Media).

Many authors have disgraced themselves over the years for not correctly citing their sources [1]. Expertise, talent, accuracy, intellectual curiosity, and enthusiasm must come together for a publication, and copying content is certainly not an option.

Concepts and Variations

The type of data storage that you use while writing often depends on your work environment – that is, whether you are working at your home desk or on a mobile device – the availability of the data, and your working style. Electronic card catalogs can be a great help in many situations [3].

User management and permissions play less of a role for single authors. However, the situation can get more complicated when multiple authors collaborate, share data, and try to agree on a single text or source component. In this case, open data formats and version control is what you need.

The following models can be divided into terms of local and central storage. For the programs I'm presenting, I will consider the local storage of text files, graphical programs for the desktop, and bookmarks in a web browser. A centralized, cloud-based storage distinguishes between access over a special desktop client and a web browser.

Everything Is Text

A simple example is a text file with numbered entries. Ideally, the file is sorted thematically and alphabetically by title or author, which helps in managing it and further research.

On the one hand, all UNIX/Linux standard tools can search through and edit it; on the other hand, version control systems like SVN and Git will also be amenable. If you use the Markdown style [4][5] from AsciiDoc [6] to structure your text file, the text will still remain easily readable for you and as well as for others (Listing 1). You can also edit it without any difficulty or adapt it move it into a wiki or Etherpad [7] for collaboration with co-authors.

== Markup languages and tools ==
* AsciiDoc, text-based document generation, http://www.methods.co.nz/asciidoc/
== Package management with APT and Aptitude ==
* Bruce Byfield: Apt Mastery. Installing software the Debian way,
  Linux Magazine, 108/2009, p. 76, http://www.linux-magazine.com/
  Issues/2009/108/Command-Line-Apt-get/%28language%29/eng-US
* Axel Beckert, Frank Hofmann: Dynamic Duo. Comparing the apt-get and aptitude
  package tools, Ubuntu User 18/2013, p. 46, http://www.ubuntu-user.com/
  Magazine/Archive/2013/18/Comparing-the-apt-get-and-aptitude-
  package-tools/%28language%29/eng-GB
== Package management with RPM ==
* Edward C. Bailey: Maximum RPM. Taking the Red Hat Package Manager to the
  Limit, Red Hat Inc., 2000, ISBN 1-888172-78-9, http://www.rpm.org/max-rpm/

Markdown, as a simplified markup language, is similar to email notation and aims at reworking it without further conversion steps so that a simple viewer – text editor or even web browser – can read it. If you need to convert it to an HTML, PDF, or ePub document, you can do so using AsciiDoc or Pandoc [8].

Figure 1 shows the result of converting to HTML after executing the following command:

$ asciidoc -a toc source.txt

Somewhat more complicated are the two text formats BibTeX [9] (LaTeX) and DocBook (XML) [10].

Figure 1: Reference list created with AsciiDoc based on Listing 1.

BibTeX assigns each entry a publication type and thus differentiates among articles, reports in books and collections, brochures, manuals, scientific dissertations, and conference results. Depending on the publication type, you will be required to fill in different fields for each specific entry.

Listing 2 shows the example of an entry for Edward C. Bailey's book Maximum RPM from Listing 1, for which you need the fields author or editor , title , publisher , and year . The ISBN field is optional and is assigned when you use biblatext as the BibTeX style instead of the default [11]. Figure 2 shows the results after converting Listing 2 with pdflatex and bibtex to PDF.

@book{ BaileyRPM,
        author          = {Bailey, Edward C.},
        title           = {Maximum RPM. Taking the Red Hat Package Manager to the Limit},
        publisher       = {Red Hat Inc.},
        year            = {2000},
        ISBN            = {1-888172-78-9}}

Figure 2: Book entry created with BibTeX.

The XML coding for DocBook is much more extensive and the data is already heavily pre-structured. Getting over the learning curve, however, is very helpful later when generating additional formats from your text for different output media with DocBook, XSLT, or XSL-FO combined with cascading style sheets (CSS) and putting the data into a version control system such as SVN or Git. Listing 3 shows the example of an entry with two authors taken from Listing 1.

<biblioentry>
  <abbrev>BeckertHofmannApt</abbrev>
  <biblioset relation="article">
    <title>Dynamic Duo</title>
    <subtitle>Apt-get and Aptitude (Part 1)</subtitle>
    <authorgroup>
      <author>
        <firstname>Axel</firstname>
        <surname>Beckert</surname>
      </author>
      <author>
        <firstname>Frank</firstname>
        <surname>Hofmann</surname>
      </author>
    </authorgroup>
    <artpagenums>90ff.</artpagenums>
  </biblioset>
  <biblioset relation="journal">
    <title>Ubuntu User</title>
    <pubdate>2013</pubdate>
    <issuenum>18</issuenum>
  </biblioset>
  <copyright>
    <year>2013</year>
    <holder>LinuxNewMedia, Lawrence</holder>
  </copyright>
  <issn>2040-8080</issn>
</biblioentry>