Style guidelines

This page provides some style guidelines for the grid documentation.

General

  • Use simple language. Not “The command results in an effective release of the file”, but “The command releases the file”.

Use of capitals

  • Titles With All Capitals? -> Only the first word.
  • The grid or the Grid? -> The Grid.
  • Grid Certificate or grid certificate? -> Grid certificate.
  • Certificate Authority? -> First time per page “Certificate Authority (CA)”, then CA with :abbr: tag. Same for:
    • First time per page Life Science Grid (LSG), then LSG.
    • Virtual Organisation (VO), then VO.
    • User Interface (UI), then UI.
  • GridFTP, gridFTP or gridftp? GSIdCap? -> GridFTP, GSIdCap, WebDAV
  • OutputSandbox or output sandbox? ->
    • OutputSandbox is the statement in the JDL. Better: OutputSandbox statement.
    • output sandbox is the location where the output files are returned.
  • dCache (name), startGridSession (command): no capital, even at start of sentence.

Acronyms

Shell commands

  • When you want to display commands and their output, use .. code-block:: console. Prefix each command with a $, without space.

    $echo 'Hello World!'
    Hello World!
    
  • When you want to display commands and comments, use .. code-block:: bash. Don’t prefix commands. Example:

    # 1. VOMS server: create a voms proxy with voms extensions that enables you to access the Grid for *12 hours*.
    voms-proxy-init --voms lsgrid  # Replace lsgrid with your VO
    
  • When you want to display commands, output and comments, use .. code-block:: console. Prefix commands with a $ and prefix comments with ##, otherwise they are marked up as a command. Example:

    $echo 'Hello World!'
    Hello World!
    ## Comments should be prefixed with a double ``#``.
    
  • To display the contents of a shell script, use .. code-block:: bash.

  • To display perl, use .. code-block:: perl. If a page only displays perl code, you can use .. highlight:: perl once and then :: for each code block. See Perl ToPoS for an example.

  • To display configuration files, use .. code-block:: cfg.

Markup

  • literal markup for:
    • pieces of code
    • commands
    • arguments
    • file names, hostnames
    • a specific term, when emphasis is on its name:
      • Example: a language called job description language
      • But: a JDL file is written in the job description language.
    • configuration file statements and values
  • Bold for strong emphasis. Example: “Only you are allowed to know the contents of this key.”
  • italic for moderate emphasis. Example: “You can continue only after you have completed the preparations.”