<sect1 id="s1-code-conventions">
  <title>Code Presentation Conventions</title>

  <para>In addition to the standard document conventions covered in <xref
      linkend="s1-intro-conventions">, there are some additional conventions
      related specifically to discussing source code:
  </para>

  <variablelist>
    <varlistentry>
      <term><classname>classname</classname></term>
      <listitem>
        <para>This is the name of a class in an object-oriented
          (<firstterm>OO</firstterm>) programming language.  For example, the
          class
          <classname>com.arsdigita.categorization.CategoryTreeNode</classname>.
        </para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term><methodname>method name</methodname></term>
      <listitem>
        <para>This is the name of a method in an OO programming language,
          e.g. the method <methodname>getBaseDataObjectType</methodname>.
        </para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term><function>function</function></term>
      <listitem>
        <para>The name of a function or subroutine, as in a programming
          language.  For example, the function
          <function>SecurityLogger.warn()</function>.
        </para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term><varname>variable name</varname></term>
      <listitem>
        <para>The name of a variable.  For example, the variable
          <varname>BASE_DATA_OBJECT_TYPE</varname>.
        </para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term><option>option</option></term>
      <listitem>
        <para>An option for a software command or
          <methodname>Method</methodname>.  For example, a user has been granted
          <option>read</option> privileges on an object.
        </para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term><returnvalue>return value</returnvalue></term>
      <listitem>
        <para>The value returned by a function.  For example, a method returns
          <returnvalue>null</returnvalue>.
        </para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term><replaceable>replaceable</replaceable></term>
      <listitem>
        <para>Content that may, must or will be replaced by the user or a
          program.  For example, the code is commented with
          <computeroutput>NOTE(<replaceable>n</replaceable>)</computeroutput>,
          where <replaceable>n</replaceable> is the number of the
          <computeroutput>NOTE</computeroutput>.
        </para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>program listing</term>
      <listitem>
        <para>A literal listing of all or part of a program.  The
          <computeroutput>\</computeroutput> character is used to break a line
          for printing purposes.  You will want to reconnect them back into a
          single line, preserving the spacing in the line.
        </para>

<programlisting>
import com.arsdigita.kernel.permissions.PermissionService;
import com.arsdigita.kernel.permissions.PermissionDescriptor;
import com.arsdigita.kernel.permissions.PrivilegeDescriptor;
import com.arsdigita.persistence.OID;

OID acsObject = new OID("example.MyACSObject",
new BigDecimal(50));

OID party = new OID("com.arsdigita.kernel.Group", new BigDecimal(5));


PermissionDescriptor perm =
new PermissionDescriptor(PrivilegeDescriptor.READ,
acsObject, party);

PermissionService.grantPermission(perm);
</programlisting>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>first term</term>
      <listitem>
        <para>The first occurrence of a term, such as the first time we
          introduce a <firstterm>bulletin-board</firstterm> and note its
          abbreviated form, <firstterm>bboard</firstterm>.
        </para>
      </listitem>
    </varlistentry>
  </variablelist>
</sect1>
