Project Report for Season of Docs 2019

Documentation Style Guide

= Documentation Style Guide

The following guidelines will help standardize the Tor Manual
documentation. In order to achieve and maintain a consistent
format for the Tor manual, it is essential that you read
through these guidelines before creating new content or
updating existing content in the Tor manual. Note that these
guidelines may expand over time.

== Organizing the Manual

 * All options are arranged in alphabetical order. While
 adding a new entry/option in the manual, ensure
 that it follows the current alphabetical order.

 * Mark the exceptions with an *//Out of order* comment as
 shown in the following example:

----
// Out of order because it logically belongs near the Schedulers option.
[[KISTSockBufSizeFactor]] **KISTSockBufSizeFactor** __NUM__::
    If KIST is used in Schedulers, this is a multiplier of the per-socket
    limit calculation of the KIST algorithm. (Default: 1.0)
----

== Capitalization

 * Tor should be capitalized as "Tor" (when it refers to the
 project) and written in lowercase as "tor" (when it refers
 to the program).

  * The names of operating systems should be capitalized
  according to their standard conventions as follows:
     ** Linux
     ** GNU
     ** Windows
     ** UNIX

  * All other proper nouns must be capitalized as per the
  standard convention. If you are unsure, google the term to
  find its correct capitalization convention.

== Formatting Conventions

 * All headings (including option names in the title) should
 contain an anchor that helps to create cross-reference
 hyperlinks to that heading or the option name. For instance,

 [[conf-format]]
== THE CONFIGURATION FILE FORMAT

    ** The anchor must be the shortened name of the
    heading or the option, preferably in camel case, and it
    must be enclosed within double square brackets as shown
    in the above example.

 * All option names in the title must be written in **bold**
 formatting. For instance - **ClientOnionAuthDir**.

   ** The boolean values that the option accepts must be
   specified in bold in the option title, such as,
   **ClientOnly 0|1**.

   ** The string variable that the option accepts must be
   specified in bold italics, such as,
   **ClientOnionAuthDir** *_path_*


== Hyperlinks

* Ensure that you use hyperlinks for all cross references
(links to other sections within the document). A typical
cross-reference uses one of the following formats: +
+
** _For more information about SockPort, see <<SocksPort,SocksPort>>._ +
** _See <<SocksPort,SocksPort>> for an explanation of isolation flags._

* Ensure that you use hyperlinks for the first occurrence of
any external reference in the manual. For example: +
+
_See https://tools.ietf.org/html/rfc1918[RFC 1918]
 and https://tools.ietf.org/html/rfc3330[RFC 3330] for more details about internal
and reserved IP address space_.