|
|
|
|
|
<!DOCTYPE html>
|
|
|
|
|
|
|
|
|
|
|
|
<html >
|
|
|
|
|
|
<head>
|
|
|
|
|
|
<meta charset="utf-8" />
|
|
|
|
|
|
<title>Style Guide for Documentation — SeisComP Release documentation</title>
|
|
|
|
|
|
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
|
|
|
|
|
|
<link rel="stylesheet" href="../_static/seiscomp.css" type="text/css" />
|
|
|
|
|
|
<link rel="stylesheet" type="text/css" href="../_static/graphviz.css" />
|
|
|
|
|
|
<script type="text/javascript" src="../_static/seiscomp.js"></script>
|
|
|
|
|
|
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
|
|
|
|
|
|
<script src="../_static/jquery.js"></script>
|
|
|
|
|
|
<script src="../_static/underscore.js"></script>
|
|
|
|
|
|
<script src="../_static/doctools.js"></script>
|
|
|
|
|
|
<script src="../_static/language_data.js"></script>
|
|
|
|
|
|
<link rel="shortcut icon" href="../_static/favicon.ico"/>
|
|
|
|
|
|
<link rel="index" title="Index" href="../genindex.html" />
|
|
|
|
|
|
<link rel="search" title="Search" href="../search.html" />
|
|
|
|
|
|
<link rel="next" title="Coding Conventions" href="coding-conventions.html" />
|
|
|
|
|
|
<link rel="prev" title="Contributing Documentation" href="contributing-docs.html" />
|
|
|
|
|
|
</head>
|
|
|
|
|
|
<body>
|
|
|
|
|
|
<div class="header">
|
|
|
|
|
|
<div class="container">
|
|
|
|
|
|
<div class="brand">
|
|
|
|
|
|
<img class="logo" src="../_static/brands/seiscomp/text/white.svg"/>
|
|
|
|
|
|
<!-- span class="title">SeisComP Release</span -->
|
|
|
|
|
|
<span class="version">5.3.0</span>
|
|
|
|
|
|
</div>
|
|
|
|
|
|
</div>
|
|
|
|
|
|
</div>
|
|
|
|
|
|
<div class="nav">
|
|
|
|
|
|
<div class="container">
|
|
|
|
|
|
<div class="content"><a class="pull-right" id="sidebar-toggle">TOC</a>
|
|
|
|
|
|
|
|
|
|
|
|
<div class="related" role="navigation" aria-label="related navigation">
|
|
|
|
|
|
<ul>
|
|
|
|
|
|
<li class="right">
|
|
|
|
|
|
<a href="../genindex.html" title="General Index"
|
|
|
|
|
|
accesskey="I">
|
|
|
|
|
|
index
|
|
|
|
|
|
</a>
|
|
|
|
|
|
</li>
|
|
|
|
|
|
<li class="right">
|
|
|
|
|
|
<a href="coding-conventions.html" title="Coding Conventions"
|
|
|
|
|
|
accesskey="N">
|
|
|
|
|
|
next
|
|
|
|
|
|
</a>
|
|
|
|
|
|
</li>
|
|
|
|
|
|
<li class="right">
|
|
|
|
|
|
<a href="contributing-docs.html" title="Contributing Documentation"
|
|
|
|
|
|
accesskey="P">
|
|
|
|
|
|
previous
|
|
|
|
|
|
</a>
|
|
|
|
|
|
</li>
|
|
|
|
|
|
<li class="nav-item nav-item-0">
|
|
|
|
|
|
<a href="../index.html">Home</a>
|
|
|
|
|
|
</li>
|
|
|
|
|
|
</ul>
|
|
|
|
|
|
</div>
|
|
|
|
|
|
</div>
|
|
|
|
|
|
</div>
|
|
|
|
|
|
</div>
|
|
|
|
|
|
<div class="container">
|
|
|
|
|
|
<div class="fitted content" id="anchors-container">
|
|
|
|
|
|
<div class="body" role="main">
|
|
|
|
|
|
|
|
|
|
|
|
<div class="section" id="style-guide-for-documentation">
|
|
|
|
|
|
<span id="documentation-style-guide"></span><h1>Style Guide for Documentation<a class="headerlink" href="#style-guide-for-documentation" title="Permalink to this headline">¶</a></h1>
|
|
|
|
|
|
<div class="section" id="file-layout">
|
|
|
|
|
|
<h2>File Layout<a class="headerlink" href="#file-layout" title="Permalink to this headline">¶</a></h2>
|
|
|
|
|
|
<p>The documentation of an executable module comes as a pair of source files:</p>
|
|
|
|
|
|
<ul class="simple">
|
|
|
|
|
|
<li><p>A description XML file (.xml) giving command details, command-line and configuration parameters,</p></li>
|
|
|
|
|
|
<li><p>A documentation reST text file (.rst) gives a more-detailed module description and examples.</p></li>
|
|
|
|
|
|
</ul>
|
|
|
|
|
|
<p>Any other documentation, e.g. this style guide, tutorials, etc. only require the
|
|
|
|
|
|
documentation reST text file.</p>
|
|
|
|
|
|
<p>The reST text file should follow the guidelines in this style guide.</p>
|
|
|
|
|
|
<p>The <a class="reference internal" href="contributing-docs.html#contributing-documentation"><span class="std std-ref">Contributing Documentation</span></a> section details
|
|
|
|
|
|
the documentation requirements for executables including the structure of description XML files.</p>
|
|
|
|
|
|
</div>
|
|
|
|
|
|
<div class="section" id="documentation-syntax">
|
|
|
|
|
|
<h2>Documentation Syntax<a class="headerlink" href="#documentation-syntax" title="Permalink to this headline">¶</a></h2>
|
|
|
|
|
|
<p>A template for a typical application or module in reST is in <code class="file docutils literal notranslate"><span class="pre">doc/templates/app.rst</span></code>.
|
|
|
|
|
|
An introductory paragraph should describe the purpose of the executable.
|
|
|
|
|
|
The introduction is followed be any additional information needed to understand
|
|
|
|
|
|
the command, introduced with one or more headings.
|
|
|
|
|
|
Add information about testing and examples into their own sections.</p>
|
|
|
|
|
|
<div class="section" id="general-principles">
|
|
|
|
|
|
<h3>General principles<a class="headerlink" href="#general-principles" title="Permalink to this headline">¶</a></h3>
|
|
|
|
|
|
<ul class="simple">
|
|
|
|
|
|
<li><p>If possible, keep line lengths under 80 characters.</p></li>
|
|
|
|
|
|
<li><p>It eases later editing if sentences in the raw RST start on a new
|
|
|
|
|
|
line, even though they will flow together in the finished document.</p></li>
|
|
|
|
|
|
<li><p>It is helpful if long text objects such as HTML link text each
|
|
|
|
|
|
appear on their own line.</p>
|
|
|
|
|
|
</li>
|
|
|
|
|
|
</ul>
|
|
|
|
|
|
</div>
|
|
|
|
|
|
<div class="section" id="section-and-headings">
|
|
|
|
|
|
<span id="documentation-style-guide-headings"></span><h3>Section and headings<a class="headerlink" href="#section-and-headings" title="Permalink to this headline">¶</a></h3>
|
|
|
|
|
|
<p>Module description files do <em>not</em> require top-level headings, as the
|
|
|
|
|
|
build script will take this text and assemble it with other
|
|
|
|
|
|
description information in the appropriate part of the documentation.</p>
|
|
|
|
|
|
<p>While RST doesn’t care too much about what syntax is used for
|
|
|
|
|
|
headings, it is best to stick to one style consistently.
|
|
|
|
|
|
Thus, you will generally need only two levels of headings but you can add more.</p>
|
|
|
|
|
|
<table class="docutils align-default">
|
|
|
|
|
|
<colgroup>
|
|
|
|
|
|
<col style="width: 19%" />
|
|
|
|
|
|
<col style="width: 81%" />
|
|
|
|
|
|
</colgroup>
|
|
|
|
|
|
<thead>
|
|
|
|
|
|
<tr class="row-odd"><th class="head"><p>Level</p></th>
|
|
|
|
|
|
<th class="head"><p>Mark up beneath heading text</p></th>
|
|
|
|
|
|
</tr>
|
|
|
|
|
|
</thead>
|
|
|
|
|
|
<tbody>
|
|
|
|
|
|
<tr class="row-even"><td><p>1</p></td>
|
|
|
|
|
|
<td><p>‘ ==== ‘</p></td>
|
|
|
|
|
|
</tr>
|
|
|
|
|
|
<tr class="row-odd"><td><p>2</p></td>
|
|
|
|
|
|
<td><p>” —- “</p></td>
|
|
|
|
|
|
</tr>
|
|
|
|
|
|
<tr class="row-even"><td><p>3</p></td>
|
|
|
|
|
|
<td><p>‘ ~~~~ ‘</p></td>
|
|
|
|
|
|
</tr>
|
|
|
|
|
|
<tr class="row-odd"><td><p>4</p></td>
|
|
|
|
|
|
<td><p>‘ ^^^^ ‘</p></td>
|
|
|
|
|
|
</tr>
|
|
|
|
|
|
</tbody>
|
|
|
|
|
|
</table>
|
|
|
|
|
|
<p>Use Title Case for headings within a section, and make only the first letter uppercase for subheadings.
|
|
|
|
|
|
Higher levels, marked up with asterisks, are used for sections of the documentation.</p>
|
|
|
|
|
|
<p><strong>Example:</strong></p>
|
|
|
|
|
|
<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span>Level <span class="m">1</span> <span class="nv">Title</span>
|
|
|
|
|
|
<span class="o">=============</span>
|
|
|
|
|
|
|
|
|
|
|
|
Some text.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Level <span class="m">2</span> title
|
|
|
|
|
|
-------------
|
|
|
|
|
|
|
|
|
|
|
|
Some text
|
|
|
|
|
|
</pre></div>
|
|
|
|
|
|
</div>
|
|
|
|
|
|
<p>Parts such as Examples are marked in <strong>bold</strong>.</p>
|
|
|
|
|
|
<p>However notes and figures should use the appropriate RST directive, and don’t require their own headings.</p>
|
|
|
|
|
|
<ul class="simple">
|
|
|
|
|
|
<li><p>One blank line below headings is enough.</p></li>
|
|
|
|
|
|
<li><p>Two lines above are often used, and this looks better than one.</p></li>
|
|
|
|
|
|
</ul>
|
|
|
|
|
|
</div>
|
|
|
|
|
|
<div class="section" id="lists">
|
|
|
|
|
|
<h3>Lists<a class="headerlink" href="#lists" title="Permalink to this headline">¶</a></h3>
|
|
|
|
|
|
<p>Use numbered or unnumbered lists at several levels.</p>
|
|
|
|
|
|
<ul class="simple">
|
|
|
|
|
|
<li><p>Start list items at the first level with a capital letter. End them with a full stop.</p></li>
|
|
|
|
|
|
<li><p>Use lower-case letters for all other levels. End them with a full stop.</p></li>
|
|
|
|
|
|
</ul>
|
|
|
|
|
|
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span><span class="m">#.</span> Item 1.
|
|
|
|
|
|
<span class="m">#.</span> Item 2.
|
|
|
|
|
|
<span class="m">*</span> subitem 1.
|
|
|
|
|
|
<span class="m">#.</span> subsubitem 1.
|
|
|
|
|
|
<span class="m">#.</span> subsubitem 1.
|
|
|
|
|
|
<span class="m">*</span> subitem 2.
|
|
|
|
|
|
</pre></div>
|
|
|
|
|
|
</div>
|
|
|
|
|
|
<p><strong>Result:</strong></p>
|
|
|
|
|
|
<ol class="arabic simple">
|
|
|
|
|
|
<li><p>Item 1.</p></li>
|
|
|
|
|
|
<li><p>Item 2.</p>
|
|
|
|
|
|
<ul class="simple">
|
|
|
|
|
|
<li><p>subitem 1.</p>
|
|
|
|
|
|
<ol class="loweralpha simple">
|
|
|
|
|
|
<li><p>subsubitem 1.</p></li>
|
|
|
|
|
|
<li><p>subsubitem 2.</p></li>
|
|
|
|
|
|
</ol>
|
|
|
|
|
|
</li>
|
|
|
|
|
|
<li><p>subitem 2.</p></li>
|
|
|
|
|
|
</ul>
|
|
|
|
|
|
</li>
|
|
|
|
|
|
</ol>
|
|
|
|
|
|
</div>
|
|
|
|
|
|
<div class="section" id="other-markup-tools-and-conventions">
|
|
|
|
|
|
<h3>Other markup tools and conventions<a class="headerlink" href="#other-markup-tools-and-conventions" title="Permalink to this headline">¶</a></h3>
|
|
|
|
|
|
<ul>
|
|
|
|
|
|
<li><p><strong>Code fragments:</strong> Use the reST code-block syntax for code fragments, with
|
|
|
|
|
|
flavor “c”, “python”, “sh” or “xml” as appropriate:</p>
|
|
|
|
|
|
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>.. code-block:: sh
|
|
|
|
|
|
|
|
|
|
|
|
#!/bin/bash
|
|
|
|
|
|
echo $SEISCOMP_ROOT
|
|
|
|
|
|
</pre></div>
|
|
|
|
|
|
</div>
|
|
|
|
|
|
<p>Result:</p>
|
|
|
|
|
|
<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span><span class="ch">#!/bin/bash</span>
|
|
|
|
|
|
<span class="nb">echo</span> <span class="nv">$SEISCOMP_ROOT</span>
|
|
|
|
|
|
</pre></div>
|
|
|
|
|
|
</div>
|
|
|
|
|
|
</li>
|
|
|
|
|
|
<li><p><strong>Configuration parameters:</strong> Configuration values and options have a special syntax. Use the :confval: tag
|
|
|
|
|
|
within the module configuration:</p>
|
|
|
|
|
|
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>:confval:`foo`
|
|
|
|
|
|
</pre></div>
|
|
|
|
|
|
</div>
|
|
|
|
|
|
<p>Using this tag allows a link to be made within the documentation to that module
|
|
|
|
|
|
to the given configuration or command-line parameter of the same module.</p>
|
|
|
|
|
|
</li>
|
|
|
|
|
|
<li><p><strong>Configuration files:</strong> Use the reST :file: indicator to refer to files such as configuration files:</p>
|
|
|
|
|
|
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>:file:`$SEISCOMP_ROOT/etc/scautopick.cfg`
|
|
|
|
|
|
</pre></div>
|
|
|
|
|
|
</div>
|
|
|
|
|
|
<p>Result: <code class="file docutils literal notranslate"><span class="pre">$SEISCOMP_ROOT/etc/scautopick.cfg</span></code></p>
|
|
|
|
|
|
</li>
|
|
|
|
|
|
<li><p><strong>Programs:</strong> Use the reST :program: indicator for <cite>SeisComP</cite> programs:</p>
|
|
|
|
|
|
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>:program:`scautopick`
|
|
|
|
|
|
</pre></div>
|
|
|
|
|
|
</div>
|
|
|
|
|
|
<p>Result: <strong class="program">scautopick</strong></p>
|
|
|
|
|
|
</li>
|
|
|
|
|
|
<li><p><strong>References:</strong> Use the reST :ref: indicator for cross referencing <cite>SeisComP</cite>. documentation pages.
|
|
|
|
|
|
Use :ref: if a cross reference to the documentation is needed:</p>
|
|
|
|
|
|
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>:ref:`scautopick`
|
|
|
|
|
|
</pre></div>
|
|
|
|
|
|
</div>
|
|
|
|
|
|
<p>Result: <a class="reference internal" href="../apps/scautopick.html#scautopick"><span class="std std-ref">scautopick</span></a></p>
|
|
|
|
|
|
</li>
|
|
|
|
|
|
<li><p><strong>Glossary:</strong> Use the reST :term: indicator for referencing terms in the <cite>SeisComP</cite> <a class="reference internal" href="glossary.html#glossary"><span class="std std-ref">Glossary</span></a>:</p>
|
|
|
|
|
|
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>:term:`magnitude`
|
|
|
|
|
|
</pre></div>
|
|
|
|
|
|
</div>
|
|
|
|
|
|
<p>Result: <a class="reference internal" href="glossary.html#term-magnitude"><span class="xref std std-term">magnitude</span></a></p>
|
|
|
|
|
|
</li>
|
|
|
|
|
|
</ul>
|
|
|
|
|
|
</div>
|
|
|
|
|
|
<div class="section" id="internal-links">
|
|
|
|
|
|
<span id="documentation-style-guide-links"></span><h3>Internal links<a class="headerlink" href="#internal-links" title="Permalink to this headline">¶</a></h3>
|
|
|
|
|
|
<p>Create links to sections and subsections within and to figures the text which can be referenced.
|
|
|
|
|
|
Use unique link names, e.g. including the upper-level section name or the module name.
|
|
|
|
|
|
Use appropriate short names to fit within the texts.</p>
|
|
|
|
|
|
<p>Link with in this documentation to the section on headings:</p>
|
|
|
|
|
|
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">..</span> <span class="n">_documentation_style_guide_headings</span><span class="p">:</span>
|
|
|
|
|
|
</pre></div>
|
|
|
|
|
|
</div>
|
|
|
|
|
|
<p>Reference:</p>
|
|
|
|
|
|
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>:ref:`short name <documentation_style_guide_headings>`
|
|
|
|
|
|
</pre></div>
|
|
|
|
|
|
</div>
|
|
|
|
|
|
<p>Result: <a class="reference internal" href="#documentation-style-guide-headings"><span class="std std-ref">short name</span></a></p>
|
|
|
|
|
|
</div>
|
|
|
|
|
|
<div class="section" id="external-references">
|
|
|
|
|
|
<h3>External references<a class="headerlink" href="#external-references" title="Permalink to this headline">¶</a></h3>
|
|
|
|
|
|
<p>Do not show full citations or URLs for
|
|
|
|
|
|
external web sites within the text but make references which
|
|
|
|
|
|
are listed in the section <a class="reference internal" href="references.html#sec-references"><span class="std std-ref">References</span></a>. Procedure:</p>
|
|
|
|
|
|
<ol class="arabic">
|
|
|
|
|
|
<li><p>Add publications, external URLs, etc. as complete citation
|
|
|
|
|
|
entries to the reference list <code class="file docutils literal notranslate"><span class="pre">doc/base/references.bib</span></code>
|
|
|
|
|
|
in the base <cite>SeisComP</cite> <a class="reference internal" href="build.html#build"><span class="std std-ref">repository on Github</span></a>.</p></li>
|
|
|
|
|
|
<li><p>Cite documents within the RST file using the <em>cite</em>
|
|
|
|
|
|
directive</p>
|
|
|
|
|
|
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>:cite:p:`seiscomp`
|
|
|
|
|
|
:cite:t:`seiscomp`
|
|
|
|
|
|
</pre></div>
|
|
|
|
|
|
</div>
|
|
|
|
|
|
<p>which results in <span id="id1">[<a class="reference internal" href="references.html#id243" title="Helmholtz-Centre Potsdam - GFZ German Research Centre for Geosciences and gempa GmbH. The SeisComP seismological software package. GFZ Data Services. 2008. URL: https://www.seiscomp.de, doi:10.5880/GFZ.2.4.2020.003.">61</a>]</span> and
|
|
|
|
|
|
<span id="id2">Helmholtz-Centre Potsdam - GFZ German Research Centre for Geosciences and gempa GmbH [<a class="reference internal" href="references.html#id243" title="Helmholtz-Centre Potsdam - GFZ German Research Centre for Geosciences and gempa GmbH. The SeisComP seismological software package. GFZ Data Services. 2008. URL: https://www.seiscomp.de, doi:10.5880/GFZ.2.4.2020.003.">61</a>]</span> within the documentation HTML text.</p>
|
|
|
|
|
|
</li>
|
|
|
|
|
|
</ol>
|
|
|
|
|
|
</div>
|
|
|
|
|
|
<div class="section" id="text-boxes">
|
|
|
|
|
|
<h3>Text boxes<a class="headerlink" href="#text-boxes" title="Permalink to this headline">¶</a></h3>
|
|
|
|
|
|
<p>You may emphasize information within the text as text boxes to stand out at different levels.
|
|
|
|
|
|
Make sensible use of it!</p>
|
|
|
|
|
|
<ul>
|
|
|
|
|
|
<li><p>Hints</p>
|
|
|
|
|
|
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">..</span> <span class="n">hint</span><span class="p">::</span>
|
|
|
|
|
|
|
|
|
|
|
|
<span class="n">This</span> <span class="n">adds</span> <span class="n">a</span> <span class="n">useful</span> <span class="n">hint</span><span class="o">.</span>
|
|
|
|
|
|
</pre></div>
|
|
|
|
|
|
</div>
|
|
|
|
|
|
<p>Result:</p>
|
|
|
|
|
|
<div class="admonition hint">
|
|
|
|
|
|
<p class="admonition-title">Hint</p>
|
|
|
|
|
|
<p>This adds a useful hint.</p>
|
|
|
|
|
|
</div>
|
|
|
|
|
|
</li>
|
|
|
|
|
|
<li><p>Notes</p>
|
|
|
|
|
|
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">..</span> <span class="n">note</span><span class="p">::</span>
|
|
|
|
|
|
|
|
|
|
|
|
<span class="n">This</span> <span class="n">adds</span> <span class="n">an</span> <span class="n">extra</span> <span class="n">note</span><span class="o">.</span>
|
|
|
|
|
|
</pre></div>
|
|
|
|
|
|
</div>
|
|
|
|
|
|
<p>Result:</p>
|
|
|
|
|
|
<div class="admonition note">
|
|
|
|
|
|
<p class="admonition-title">Note</p>
|
|
|
|
|
|
<p>This adds an extra note.</p>
|
|
|
|
|
|
</div>
|
|
|
|
|
|
</li>
|
|
|
|
|
|
<li><p>Alerts</p>
|
|
|
|
|
|
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">..</span> <span class="n">caution</span><span class="p">::</span>
|
|
|
|
|
|
|
|
|
|
|
|
<span class="n">This</span> <span class="n">adds</span> <span class="n">a</span> <span class="n">heads</span><span class="o">-</span><span class="n">up</span> <span class="n">alert</span><span class="o">.</span>
|
|
|
|
|
|
</pre></div>
|
|
|
|
|
|
</div>
|
|
|
|
|
|
<p>Result:</p>
|
|
|
|
|
|
<div class="admonition caution">
|
|
|
|
|
|
<p class="admonition-title">Caution</p>
|
|
|
|
|
|
<p>This adds a heads-up alert.</p>
|
|
|
|
|
|
</div>
|
|
|
|
|
|
</li>
|
|
|
|
|
|
<li><p>Warnings</p>
|
|
|
|
|
|
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">..</span> <span class="n">warning</span><span class="p">::</span>
|
|
|
|
|
|
|
|
|
|
|
|
<span class="n">This</span> <span class="n">adds</span> <span class="n">an</span> <span class="n">important</span> <span class="n">warning</span><span class="o">.</span>
|
|
|
|
|
|
</pre></div>
|
|
|
|
|
|
</div>
|
|
|
|
|
|
<p>Result:</p>
|
|
|
|
|
|
<div class="admonition warning">
|
|
|
|
|
|
<p class="admonition-title">Warning</p>
|
|
|
|
|
|
<p>This adds an important warning.</p>
|
|
|
|
|
|
</div>
|
|
|
|
|
|
</li>
|
|
|
|
|
|
</ul>
|
|
|
|
|
|
</div>
|
|
|
|
|
|
</div>
|
|
|
|
|
|
<div class="section" id="english-language">
|
|
|
|
|
|
<h2>English Language<a class="headerlink" href="#english-language" title="Permalink to this headline">¶</a></h2>
|
|
|
|
|
|
<ul class="simple">
|
|
|
|
|
|
<li><p>SeisComP (capital P), not SeisComP 3 or SC3.</p></li>
|
|
|
|
|
|
<li><p><cite>SeisComP</cite> module names are proper nouns, even though written with lower case.
|
|
|
|
|
|
Thus they do not need an article.</p>
|
|
|
|
|
|
<ul>
|
|
|
|
|
|
<li><p>Correct: “Although <strong class="program">scmaster</strong> receives a message”</p></li>
|
|
|
|
|
|
<li><p>Incorrect: “Although the scmaster receives a message…”</p></li>
|
|
|
|
|
|
</ul>
|
|
|
|
|
|
</li>
|
|
|
|
|
|
</ul>
|
|
|
|
|
|
<p>A sentence may begin with a lower case module name e.g. “scmaster has five modes…”
|
|
|
|
|
|
avoiding this: “The <strong class="program">scmaster</strong> module has…”</p>
|
|
|
|
|
|
<ul>
|
|
|
|
|
|
<li><p>Word separation:</p>
|
|
|
|
|
|
<ul class="simple">
|
|
|
|
|
|
<li><p>Separate words:
|
|
|
|
|
|
base class, wave number, time span</p></li>
|
|
|
|
|
|
<li><p>One word:
|
|
|
|
|
|
aftershock, foreshock, <em>and mainshock too</em>,
|
|
|
|
|
|
bandpass, eigenperiod etc., metadata, standalone, username, workflow, waveform</p></li>
|
|
|
|
|
|
<li><p>Difficult:
|
|
|
|
|
|
high-pass filter; command line; command-line parameter</p></li>
|
|
|
|
|
|
</ul>
|
|
|
|
|
|
</li>
|
|
|
|
|
|
<li><p>Hyphenation for compound adjectives: yes, before a noun; after verb to be is harder.
|
|
|
|
|
|
See the <a class="reference external" href="https://english.stackexchange.com/questions/65630/you-should-be-well-organised-or-you-should-be-well-organised">discussion</a> <a class="footnote-reference brackets" href="#id3" id="id4">1</a>, e.g.:</p>
|
|
|
|
|
|
<ul class="simple">
|
|
|
|
|
|
<li><p>Use command-line parameters.</p></li>
|
|
|
|
|
|
<li><p>Type on the command line.</p></li>
|
|
|
|
|
|
</ul>
|
|
|
|
|
|
</li>
|
|
|
|
|
|
<li><p>Spelling:</p>
|
|
|
|
|
|
<p>Use American English:</p>
|
|
|
|
|
|
<ul class="simple">
|
|
|
|
|
|
<li><p>With ‘z’: digitizer, realize, visualize, synchronize, behavior, color.</p></li>
|
|
|
|
|
|
<li><p>With ‘s’: license.</p></li>
|
|
|
|
|
|
<li><p>Center, data center.</p></li>
|
|
|
|
|
|
</ul>
|
|
|
|
|
|
</li>
|
|
|
|
|
|
<li><p>Case:</p>
|
|
|
|
|
|
<ul class="simple">
|
|
|
|
|
|
<li><p>SEED, miniSEED (miniSEED in <a class="reference external" href="https://github.com/iris-edu/libmseed/wiki">libmseed documentation</a> <a class="footnote-reference brackets" href="#id5" id="id6">2</a>, or MiniSEED,
|
|
|
|
|
|
but Mini-SEED appears in Appendix G of the <a class="reference external" href="https://www.fdsn.org/pdf/SEEDManual_V2.4.pdf">Seed Reference Manual</a> <a class="footnote-reference brackets" href="#id7" id="id8">3</a>.)</p></li>
|
|
|
|
|
|
<li><p>Ctrl+S for ‘control’ key plus ‘s’.</p></li>
|
|
|
|
|
|
<li><p>MySQL, PostgreSQL, MariaDB</p></li>
|
|
|
|
|
|
</ul>
|
|
|
|
|
|
</li>
|
|
|
|
|
|
<li><p>Abbreviations:</p>
|
|
|
|
|
|
<ul class="simple">
|
|
|
|
|
|
<li><p>e.g., i.e.</p></li>
|
|
|
|
|
|
<li><p>STA, LTA, STA/LTA detector</p></li>
|
|
|
|
|
|
<li><p>TAR file</p></li>
|
|
|
|
|
|
</ul>
|
|
|
|
|
|
</li>
|
|
|
|
|
|
</ul>
|
|
|
|
|
|
</div>
|
|
|
|
|
|
<div class="section" id="adding-images">
|
|
|
|
|
|
<span id="documentation-style-guide-images"></span><h2>Adding Images<a class="headerlink" href="#adding-images" title="Permalink to this headline">¶</a></h2>
|
|
|
|
|
|
<div class="section" id="code-implementation">
|
|
|
|
|
|
<h3>Code implementation<a class="headerlink" href="#code-implementation" title="Permalink to this headline">¶</a></h3>
|
|
|
|
|
|
<ul class="simple">
|
|
|
|
|
|
<li><p>Add images with fixed width.</p></li>
|
|
|
|
|
|
<li><p>Add image captions.</p></li>
|
|
|
|
|
|
<li><p>Store images in a separate directory of below the directory where the
|
|
|
|
|
|
documentation is kept.</p></li>
|
|
|
|
|
|
</ul>
|
|
|
|
|
|
<p>Example for an image which can be enlarge by mouse click:</p>
|
|
|
|
|
|
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span><span class="p">..</span> <span class="ow">figure</span><span class="p">::</span> media/image.png
|
|
|
|
|
|
<span class="nc">:alt:</span> <span class="nf">image one</span>
|
|
|
|
|
|
<span class="nc">:width:</span> <span class="nf">10cm</span>
|
|
|
|
|
|
<span class="nc">:align:</span> <span class="nf">center</span>
|
|
|
|
|
|
|
|
|
|
|
|
Image one.
|
|
|
|
|
|
</pre></div>
|
|
|
|
|
|
</div>
|
|
|
|
|
|
<p>Example for images in two columns which cannot be enlarged. Up to 4 columns are possible.
|
|
|
|
|
|
Compare with the <a class="reference internal" href="concepts/configuration.html#concepts-configuration-configs"><span class="std std-ref">concept section on configuration</span></a>:</p>
|
|
|
|
|
|
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span><span class="p">..</span> <span class="ow">raw</span><span class="p">::</span> html
|
|
|
|
|
|
|
|
|
|
|
|
<span class="nt"><div class="two column layout"></span>
|
|
|
|
|
|
|
|
|
|
|
|
<span class="p">..</span> <span class="ow">figure</span><span class="p">::</span> ../media/scconfig_no_bindings.png
|
|
|
|
|
|
<span class="nc">:alt:</span> <span class="nf">scconfig: bindings configurations</span>
|
|
|
|
|
|
|
|
|
|
|
|
scconfig modules panel indicating that no bindings can be configured.
|
|
|
|
|
|
|
|
|
|
|
|
<span class="p"> ..</span> <span class="ow">figure</span><span class="p">::</span> ../media/scconfig_has_bindings.png
|
|
|
|
|
|
<span class="nc">:alt:</span> <span class="nf">scconfig: no bindings configurations</span>
|
|
|
|
|
|
|
|
|
|
|
|
scconfig modules panel indicating that bindings can be configured.
|
|
|
|
|
|
|
|
|
|
|
|
<span class="p"> ..</span> <span class="ow">raw</span><span class="p">::</span> html
|
|
|
|
|
|
|
|
|
|
|
|
</div>
|
|
|
|
|
|
</pre></div>
|
|
|
|
|
|
</div>
|
|
|
|
|
|
</div>
|
|
|
|
|
|
<div class="section" id="image-style-and-format">
|
|
|
|
|
|
<h3>Image style and format<a class="headerlink" href="#image-style-and-format" title="Permalink to this headline">¶</a></h3>
|
|
|
|
|
|
<ul class="simple">
|
|
|
|
|
|
<li><p>Images shall be informative.</p></li>
|
|
|
|
|
|
<li><p>Images must not have any offensive or inappropriate content.</p></li>
|
|
|
|
|
|
<li><p>Use PNG format.</p></li>
|
|
|
|
|
|
<li><p>Make the important image details readable at the normal image size without enlargement.</p></li>
|
|
|
|
|
|
<li><p>Images shall be optimized for file size.</p></li>
|
|
|
|
|
|
<li><p>Images should have a frame, e.g. a window frame.</p></li>
|
|
|
|
|
|
<li><p>Avoid private information on images.</p></li>
|
|
|
|
|
|
<li><p>Do not show desktop background unless required.</p></li>
|
|
|
|
|
|
<li><p>Images from <cite>SeisComP</cite> GUIs can be screenshots.</p></li>
|
|
|
|
|
|
<li><p>Do not create screenshots from applications started remotely with X-forwarding.
|
|
|
|
|
|
X-forwarding may distort the application features.</p></li>
|
|
|
|
|
|
</ul>
|
|
|
|
|
|
</div>
|
|
|
|
|
|
</div>
|
|
|
|
|
|
<div class="section" id="references">
|
|
|
|
|
|
<h2>References<a class="headerlink" href="#references" title="Permalink to this headline">¶</a></h2>
|
|
|
|
|
|
<dl class="footnote brackets">
|
|
|
|
|
|
<dt class="label" id="id3"><span class="brackets"><a class="fn-backref" href="#id4">1</a></span></dt>
|
|
|
|
|
|
<dd><p><a class="reference external" href="https://english.stackexchange.com/questions/65630/you-should-be-well-organised-or-you-should-be-well-organised">https://english.stackexchange.com/questions/65630/you-should-be-well-organised-or-you-should-be-well-organised</a></p>
|
|
|
|
|
|
</dd>
|
|
|
|
|
|
<dt class="label" id="id5"><span class="brackets"><a class="fn-backref" href="#id6">2</a></span></dt>
|
|
|
|
|
|
<dd><p><a class="reference external" href="https://github.com/iris-edu/libmseed/wiki">https://github.com/iris-edu/libmseed/wiki</a></p>
|
|
|
|
|
|
</dd>
|
|
|
|
|
|
<dt class="label" id="id7"><span class="brackets"><a class="fn-backref" href="#id8">3</a></span></dt>
|
|
|
|
|
|
<dd><p><a class="reference external" href="https://www.fdsn.org/pdf/SEEDManual_V2.4.pdf">https://www.fdsn.org/pdf/SEEDManual_V2.4.pdf</a></p>
|
|
|
|
|
|
</dd>
|
|
|
|
|
|
</dl>
|
|
|
|
|
|
</div>
|
|
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<div id="anchors-bottom"></div>
|
|
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
|
|
<div class="sidebar" role="navigation" aria-label="main navigation">
|
|
|
|
|
|
<div id="anchors-top"></div>
|
|
|
|
|
|
<div id="anchors" class="content">
|
|
|
|
|
|
<div id="searchbox" style="display: none" role="search">
|
|
|
|
|
|
<h3 id="searchlabel">Quick search</h3>
|
|
|
|
|
|
<div class="searchformwrapper">
|
|
|
|
|
|
<form class="search" action="../search.html" method="get">
|
|
|
|
|
|
<input type="text" name="q" aria-labelledby="searchlabel" />
|
|
|
|
|
|
<input type="submit" value="Go" />
|
|
|
|
|
|
</form>
|
|
|
|
|
|
</div>
|
|
|
|
|
|
</div>
|
|
|
|
|
|
<script>$('#searchbox').show(0);</script>
|
|
|
|
|
|
<h3><a href="../index.html">Table of Contents</a></h3>
|
|
|
|
|
|
<ul>
|
|
|
|
|
|
<li><a class="reference internal" href="#">Style Guide for Documentation</a><ul>
|
|
|
|
|
|
<li><a class="reference internal" href="#file-layout">File Layout</a></li>
|
|
|
|
|
|
<li><a class="reference internal" href="#documentation-syntax">Documentation Syntax</a><ul>
|
|
|
|
|
|
<li><a class="reference internal" href="#general-principles">General principles</a></li>
|
|
|
|
|
|
<li><a class="reference internal" href="#section-and-headings">Section and headings</a></li>
|
|
|
|
|
|
<li><a class="reference internal" href="#lists">Lists</a></li>
|
|
|
|
|
|
<li><a class="reference internal" href="#other-markup-tools-and-conventions">Other markup tools and conventions</a></li>
|
|
|
|
|
|
<li><a class="reference internal" href="#internal-links">Internal links</a></li>
|
|
|
|
|
|
<li><a class="reference internal" href="#external-references">External references</a></li>
|
|
|
|
|
|
<li><a class="reference internal" href="#text-boxes">Text boxes</a></li>
|
|
|
|
|
|
</ul>
|
|
|
|
|
|
</li>
|
|
|
|
|
|
<li><a class="reference internal" href="#english-language">English Language</a></li>
|
|
|
|
|
|
<li><a class="reference internal" href="#adding-images">Adding Images</a><ul>
|
|
|
|
|
|
<li><a class="reference internal" href="#code-implementation">Code implementation</a></li>
|
|
|
|
|
|
<li><a class="reference internal" href="#image-style-and-format">Image style and format</a></li>
|
|
|
|
|
|
</ul>
|
|
|
|
|
|
</li>
|
|
|
|
|
|
<li><a class="reference internal" href="#references">References</a></li>
|
|
|
|
|
|
</ul>
|
|
|
|
|
|
</li>
|
|
|
|
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
|
|
<h4>Previous topic</h4>
|
|
|
|
|
|
<p class="topless"><a href="contributing-docs.html"
|
|
|
|
|
|
title="previous chapter">Contributing Documentation</a></p>
|
|
|
|
|
|
<h4>Next topic</h4>
|
|
|
|
|
|
<p class="topless"><a href="coding-conventions.html"
|
|
|
|
|
|
title="next chapter">Coding Conventions</a></p>
|
|
|
|
|
|
<div role="note" aria-label="source link">
|
|
|
|
|
|
<h3>This Page</h3>
|
|
|
|
|
|
<ul class="this-page-menu">
|
|
|
|
|
|
<li><a href="../_sources/base/style-guide.rst.txt"
|
|
|
|
|
|
rel="nofollow">Show Source</a></li>
|
|
|
|
|
|
</ul>
|
|
|
|
|
|
</div>
|
|
|
|
|
|
</div>
|
|
|
|
|
|
</div>
|
|
|
|
|
|
</div>
|
|
|
|
|
|
</div>
|
|
|
|
|
|
<div class="footer">
|
|
|
|
|
|
<div class="container">
|
|
|
|
|
|
<div class="horizontal layout content">
|
|
|
|
|
|
<a class="fade-in" href="https://www.gempa.de" target="_blank">
|
|
|
|
|
|
<img class="brand" src="../_static/brands/gempa.svg"/>
|
|
|
|
|
|
</a>
|
|
|
|
|
|
<div class="stretched align-center fitted content">
|
|
|
|
|
|
<div>
|
|
|
|
|
|
Version <b>5.3.0</b> Release
|
|
|
|
|
|
</div>
|
|
|
|
|
|
<div class="copyright">
|
|
|
|
|
|
Copyright © gempa GmbH, GFZ Potsdam.
|
|
|
|
|
|
</div>
|
|
|
|
|
|
</div>
|
|
|
|
|
|
<a class="fade-in" href="https://www.gfz-potsdam.de" target="_blank">
|
|
|
|
|
|
<img class="brand" src="../_static/brands/gfz.svg"/>
|
|
|
|
|
|
</a>
|
|
|
|
|
|
</div>
|
|
|
|
|
|
</div>
|
|
|
|
|
|
</div>
|
|
|
|
|
|
</body>
|
|
|
|
|
|
</html>
|
