Reference Material

Conventions for Report Writing

The project has strict standards in respect of conventions even in reports that contain no code, ultimately to support the ‘write once, use many times’ concept, so that text may be cut, edited and pasted into source code, or indeed used safely to define variable names, constraints on their values and physical dimensions. Thus, since many compilers support only ASCII characters, only ASCII is allowed in reports. Similarly, very long lines (typically arising from MS Windows wordprocessing) should be split at the ends of sentences, and preferably so that maximum line length is \(120\) characters. A number of tools are available in tex/importools. Contributors may use their style of choice for both reports (and code) provided they follow systems that allow for automatic conversion to the conventions expected in the NEPTUNE repositories, and are prepared to help construct gitlab runners and github hooks to this end. However, it will be generally found easier to use LaTeX and bibtex as indicated below.

For shorter documents it is acceptable to use Markdown in the ‘dialect’ defined by PANDOC, see Annex A of ref. [3]. Resulting .md files frequently convert straightforwardly to LaTeX format, using the md2tex.bash script from tex/importools.

General textual issues

It is helpful to use LaTeX newcommand for certain keywords where they have a special format or because the terminology is not fully established. Although some do not, most people do find variations in use of spelling, punctuation, capitalisation etc. to be irritating, and so the following conventions will be enforced where possible:

• • use of LaTeX newcommand for , viz. \papp and \exc instead of explicit proxyapp or mini-app and ExCALIBUR respectively

• • punctuation, viz. eg.\ rather than e.g.

• • hyphenation, generally to be avoided because LaTeX may use it to break lines, viz. finite element rather than finite-element (or simply FE), opensource rather than open source, major exception is abbreviation of dimensions (below).

• • capitalisation, eg. Exascale rather than exascale

• • abbreviation of dimensions, 2-D and 3-D preferred to 2D and 3D or 2d and 3d

• • spelling, UK English preferred, and ’-ise’ etc. preferred to ’-ize’

• • no spaces between authors’ initials in bibtex files (see also Section 11.1)

• • consistent usage of acronyms, employing the table of Section 11.2

• • consistent usage of mathematical symbols, employing the table of Section 11.3

Citations

Regarding citations, those for unpublished reports MUST include a link to a website, such as arXiv, and it would be helpful if links to other open-access material were also given. Use of the following conventions for constructing the keys of citations should help avoid clashes:

• 1. For published papers, use where possible an \(8\)-character alphanumeric for published papers, consisting of the first two letters of the first author’s name, the last two digits of the year in the Gregorian calendar, and the first \(4\) letters of the first significant word (ie. not ‘The’ or ‘On’) of the title, preserving capitalisations. Thus the paper ref. [97] by Bangerth and Heister, published in 2013 and entitled ‘What makes computational open source software libraries successful?’, has key ‘Ba13What’.

• 2. Books and theses should be keyed with the full second-name(s) of the author(s) strung together without capitalisation, up to a limit of approx. \(30\) characters, using ‘etal’ to indicate any omitted author-names. As an example, the book by Rouson, Xia and Xu ref. [96] has key ‘rousonxiaxu’.

• 3. If there are duplicates in different files, then preface each key with the name of the .bib file it is in, for other duplicates within a file, add ‘2’, ‘3’ etc. to the end of the key.

Software Compatibility

When discussing software in the text, the following conventions in LaTeX are proposed:

• • Small capitals denote a package name, use {\textsc or abbreviation \F{

• • Italics denote a program name, use {\textit or abbreviation \I{

• • Fixed width font denotes any code name or fragment which is not otherwise obviously source code, use {\texttt or abbreviation \T{

There is no need for special fonts if the object is identified by a suitable suffix, thus “_m" for a module containing executable code, “_h" or “.h" for an object description or namespace code, “.cpp" for name of file containing C++ source, “.exe" for an executable, etc. Similarly file suffices that imply a particular format or software for their interpretation, may simply be written with a leading stop, eg. “.html" and “.exe".

In order to ensure smooth transliteration from mathematical symbols to the names of the software variables, Table 11.1 lists the recommended two-character equivalents for LaTeX symbols used in the definition of mathematical symbols.