| |
@@ -0,0 +1,278 @@
|
| |
+ = Document Markup
|
| |
+
|
| |
+ == AsciiDoc
|
| |
+
|
| |
+ Documentation is written using
|
| |
+ http://www.methods.co.nz/asciidoc/index.html[AsciiDoc] as extended by
|
| |
+ http://asciidoctor.org/[Asciidoctor].
|
| |
+
|
| |
+ == Formatting Guidelines
|
| |
+
|
| |
+ When writing the following formatting rules apply to the AsciiDoc source
|
| |
+ as used in Fedora:
|
| |
+
|
| |
+ * Wrap paragraphs sensibly (~80 chars) to improve readability and diffs.
|
| |
+
|
| |
+ * Format lists visually to make reading the source easy.
|
| |
+
|
| |
+ * Headers are written in the single-line AsciiDoc format with equal
|
| |
+ signs only on the left.
|
| |
+
|
| |
+ * The title, which is the first line of the document, is the only level 1
|
| |
+ ( = ) title. Section headers within the topic must be level 2 ( == )
|
| |
+ or lower.
|
| |
+
|
| |
+ * Section anchors must be all lowercase letters, with no line spaces
|
| |
+ between the anchor and the section title. Anchors are typically the
|
| |
+ same as their title with the spaces replaces by dashes.
|
| |
+ +
|
| |
+ ----
|
| |
+ [[section-anchor-name]]
|
| |
+ === Section Title
|
| |
+ ----
|
| |
+
|
| |
+ * In general, try to generalize documentation to eliminate the need to
|
| |
+ reference Fedora or a specific version of Fedora. If this cannot
|
| |
+ be avoided, use the entities below instead of actually writing out
|
| |
+ the reference. This allows us to easily update version numbers and
|
| |
+ names as needed.
|
| |
+ +
|
| |
+ FIXME - add entities
|
| |
+ +
|
| |
+ For example:
|
| |
+ +
|
| |
+ ----
|
| |
+ You can deploy applications on {product-title}.
|
| |
+ ----
|
| |
+
|
| |
+ * Links to other AsciiDoc files are always created with `link:`. Links to
|
| |
+ external websites are created using the short format `url[text]`.
|
| |
+ +
|
| |
+ FIXME - should we use xref for internal references
|
| |
+ +
|
| |
+ For example:
|
| |
+ +
|
| |
+ ----
|
| |
+ You should fully understand link:other.adoc[foo, bar and baz] before attempting this procedure.
|
| |
+ The repository of http://example.com[examples] contains many functional prototypes for you to extend.
|
| |
+ ----
|
| |
+ +
|
| |
+ Whenever possible the link to another topic should be part of the actual
|
| |
+ sentence. Avoid creating links as a separate sentence that begins with
|
| |
+ "See [this topic] for more information on x".
|
| |
+
|
| |
+ * The following elements are marked up semantically as `[tag]#content#`
|
| |
+ where tag is one of the following:
|
| |
+
|
| |
+ ** acronym - An often pronounceable word made from the initial (or
|
| |
+ selected) letters of a name or phrase
|
| |
+ ** application - The name of a software program
|
| |
+ ** citetitle - The title of a cited work
|
| |
+ ** command - The name of an executable program or other software command
|
| |
+ ** filename - The name of a file
|
| |
+ ** literal - Inline text that is some literal value
|
| |
+ ** option - An option for a software command
|
| |
+ ** package - A name of a software package (e.g. a RPM)
|
| |
+ ** parameter - A value or a symbolic reference to a value
|
| |
+ ** replaceable - Content that may or must be replaced by the user
|
| |
+ ** systemitem - A system-related item or term
|
| |
+
|
| |
+
|
| |
+ * The following elements are marked up semantically the same way as:
|
| |
+ `[button]#content#` . These are all marked up using `button`.
|
| |
+
|
| |
+ ** guibutton
|
| |
+ ** guilabel
|
| |
+ ** guimenuitem
|
| |
+ ** guimenu
|
| |
+ ** guisubmenu
|
| |
+ ** keycap
|
| |
+ ** keycombo
|
| |
+
|
| |
+ * Sharing content between files
|
| |
+ +
|
| |
+ If you want to share content from one topic so that it appears in another topic,
|
| |
+ you can use the `include` directive. See the Asciidoctor documentation for
|
| |
+ details:
|
| |
+ +
|
| |
+ http://asciidoctor.org/docs/user-manual/#include-partial
|
| |
+ +
|
| |
+ If you find that you need to include content from one topic multiple times into
|
| |
+ another topic, see the following usage:
|
| |
+ +
|
| |
+ http://asciidoctor.org/docs/user-manual/#include-multiple
|
| |
+
|
| |
+ * Images
|
| |
+ If you want to link to an image:
|
| |
+ *
|
| |
+ 1. Put it in `<topic_dir>/images`
|
| |
+ 2. In the topic document, use this format to link to an image:
|
| |
+ +
|
| |
+ ----
|
| |
+ image::<name_of_image>[image]
|
| |
+ ----
|
| |
+ +
|
| |
+ You only need to specify `<name_of_image>`. The build mechanism automatically specifies the file path.
|
| |
+
|
| |
+ * System blocks, table delimiters
|
| |
+ +
|
| |
+ For all of the system blocks including table delimiters, use four characters. For example:
|
| |
+ +
|
| |
+ ....
|
| |
+ |=== for tables
|
| |
+ ---- for code blocks
|
| |
+ ....
|
| |
+
|
| |
+ * Code blocks
|
| |
+ Code blocks are used to show examples of command screen outputs, or configuration files. When using command blocks always use the actual values for any items that a user would normally replace. Code blocks should represent exactly what a customer would see on their screen. If you need to expand or provide information on what some of the contents of a screen output or configuration file represent, then use callouts to provide that information.
|
| |
+ +
|
| |
+ Follow these general guidelines when using code blocks:
|
| |
+ +
|
| |
+ * Do NOT show replaceables within code blocks.
|
| |
+ +
|
| |
+ * Do NOT use any markup in code blocks; code blocks generally do not accept any markup
|
| |
+ +
|
| |
+ * Try to use callouts to provide information on what the output represents when required
|
| |
+ +
|
| |
+ For all code blocks, you must include an empty line above a code block.
|
| |
+ +
|
| |
+ Acceptable:
|
| |
+ +
|
| |
+ ....
|
| |
+ Lorem ipsum
|
| |
+
|
| |
+ ----
|
| |
+ $ lorem.sh
|
| |
+ ----
|
| |
+ ....
|
| |
+ +
|
| |
+ Not acceptable:
|
| |
+ +
|
| |
+ ....
|
| |
+ Lorem ipsum
|
| |
+ ----
|
| |
+ $ lorem.sh
|
| |
+ ----
|
| |
+ ....
|
| |
+ +
|
| |
+ Without the line spaces the content is likely to be not parsed correctly.
|
| |
+
|
| |
+ * Inline Code or Commands
|
| |
+ Do NOT show full commands or command syntax inline within a sentence. The next section covers how to show commands and command syntax.
|
| |
+ +
|
| |
+ Only use case for inline commands would be general commands and operations, without replaceables and command options. In this case an inline command is marked up using the back ticks:
|
| |
+ +
|
| |
+ When writing an inline command example do not nest markup. For example, write `[command]#ls -l#` not `[command]#ls [option]#-l##`
|
| |
+ +
|
| |
+ ....
|
| |
+ Use the `GET` operation to do x.
|
| |
+ ....
|
| |
+ +
|
| |
+ This renders as:
|
| |
+ +
|
| |
+ Use the `GET` operation to do x.
|
| |
+
|
| |
+ ** Command syntax and examples
|
| |
+ The main distinction between showing command syntax and example is that a command syntax should just show customers how to use the command without real values. An example on the other hand should show the command with actual values with an example output of that command, where applicable.
|
| |
+
|
| |
+ ** Command syntax
|
| |
+ To markup command syntax, use the code block and wrap the replaceables in <> with the required command parameters, as shown in the following example. Do NOT use commands or command syntax inline with sentences.
|
| |
+ +
|
| |
+ ....
|
| |
+ The following command returns a list of objects for the specified object type:
|
| |
+
|
| |
+ ----
|
| |
+ oc get <object_type> <object_id>
|
| |
+ ----
|
| |
+ ....
|
| |
+ +
|
| |
+ This would render as follows:
|
| |
+ +
|
| |
+ The following command returns a list of objects for the specified object type:
|
| |
+ +
|
| |
+ ----
|
| |
+ oc get <object_type> <object_id>
|
| |
+ ----
|
| |
+
|
| |
+ ***Examples
|
| |
+ As mentioned an example of a command should use actual values and also show an output of the command, as shown in the following example. In some a heading may not be required.
|
| |
+ +
|
| |
+ ....
|
| |
+ In the following example the `oc get` operation returns a complete list of services that are currently defined.
|
| |
+
|
| |
+ .Example Title
|
| |
+ ====
|
| |
+
|
| |
+ ----
|
| |
+ $ oc get se
|
| |
+ NAME LABELS SELECTOR IP PORT
|
| |
+ kubernetes component=apiserver,provider=kubernetes <none> 172.30.17.96 443
|
| |
+ kubernetes-ro component=apiserver,provider=kubernetes <none> 172.30.17.77 80
|
| |
+ docker-registry <none> name=registrypod 172.30.17.158 5001
|
| |
+ ----
|
| |
+ ====
|
| |
+ ....
|
| |
+ +
|
| |
+ This would render as shown:
|
| |
+ +
|
| |
+ In the following example the `oc get` operation returns a complete list of services that are currently defined.
|
| |
+ +
|
| |
+ .Example Title
|
| |
+ ====
|
| |
+
|
| |
+ ----
|
| |
+ $ oc get se
|
| |
+ NAME LABELS SELECTOR IP PORT
|
| |
+ kubernetes component=apiserver,provider=kubernetes <none> 172.30.17.96 443
|
| |
+ kubernetes-ro component=apiserver,provider=kubernetes <none> 172.30.17.77 80
|
| |
+ docker-registry <none> name=registrypod 172.30.17.158 5001
|
| |
+ ----
|
| |
+ ====
|
| |
+
|
| |
+
|
| |
+ *** Lists
|
| |
+ Lists are created as shown in this example:
|
| |
+ +
|
| |
+ ....
|
| |
+ . Item 1 (2 spaces between the period and the first character)
|
| |
+
|
| |
+ . Item 2
|
| |
+
|
| |
+ . Item 3
|
| |
+ ....
|
| |
+ +
|
| |
+ This will render as such:
|
| |
+
|
| |
+ . Item 1
|
| |
+
|
| |
+ . Item 2
|
| |
+
|
| |
+ . Item 3
|
| |
+ +
|
| |
+ If you need to add any text, admonitions, or code blocks you need to add the continuous +, as shown in the example:
|
| |
+ +
|
| |
+ ....
|
| |
+ . Item 1
|
| |
+ +
|
| |
+ ----
|
| |
+ some code block
|
| |
+ ----
|
| |
+
|
| |
+ . Item 2
|
| |
+
|
| |
+ . Item 3
|
| |
+ ....
|
| |
+ +
|
| |
+ This renders as shown:
|
| |
+ +
|
| |
+ . Item 1
|
| |
+ +
|
| |
+ ----
|
| |
+ some code block
|
| |
+ ----
|
| |
+
|
| |
+ . Item 2
|
| |
+
|
| |
+ . Item 3
|
| |
+
|
| |
+ FIXME - How to do NOTES, WARNINGS, AND ADMONITIONS
|
| |
bex
commented 7 years ago
Comments appreciated - this isn't final yet or ready to merge.