SUSE Documentation Style Guide (AsciiDoc) #
This guide provides answers to writing, style and layout questions commonly arising when editing SUSE documentation. The GeekoDoc, DocBook and AsciiDoc markup reference in this guide will help you choose the right formatting options for your purpose. Following this guide will make your documentation more understandable and easier to translate.
- 1 Working with AsciiDoc
- 2 Writing technical documentation
- 3 Documentation content
- 4 Names of example items
- 5 Outline of a manual
- 6 Writing for the Web
- 7 Language
- 7.1 Abbreviations
- 7.2 Biases and inclusiveness
- 7.3 Capitalization of headings and titles
- 7.4 Colons
- 7.5 Commas
- 7.6 Contractions
- 7.7 Dashes
- 7.8 End of sentence punctuation
- 7.9 File and directory names
- 7.10 Headings
- 7.11 Hyphens
- 7.12 Lists
- 7.13 Numbers and measurements
- 7.14 Possessives
- 7.15 Prefixes
- 7.16 Quotations
- 7.17 Semicolons
- 7.18 Sentence structure
- 7.19 Slashes
- 7.20 Tense
- 7.21 Tone and voice
- 7.22 Trademarks
- 7.23 User interface items
- 8 Structure and markup
- 8.1 Admonitory and advisory paragraphs
- 8.2 Callouts
- 8.3 Command-line input and command-line output
- 8.4 Cross-references
- 8.5 Emphasis
- 8.6 Examples
- 8.7 External links
- 8.8 External links to SUSE documentation
- 8.9 Figures
- 8.10 Glossaries
- 8.11 Identifiers
- 8.12 Lists
- 8.13 Keys and key combinations
- 8.14 Outline levels and sectioning
- 8.15 Procedures
- 8.16 Profiling
- 8.17 Questions and answers
- 8.18 References to other external resources
- 8.19 Tables
- 8.20 User interface items
- 9 Managing documents
- 10 Working with Smart Docs
- A Terminology and general vocabulary
- B Contributors
- C GNU Free Documentation License
- C1 PREAMBLE
- C2 APPLICABILITY AND DEFINITIONS
- C3 VERBATIM COPYING
- C4 COPYING IN QUANTITY
- C5 MODIFICATIONS
- C6 COMBINING DOCUMENTS
- C7 COLLECTIONS OF DOCUMENTS
- C8 AGGREGATION WITH INDEPENDENT WORKS
- C9 TRANSLATION
- C10 TERMINATION
- C11 FUTURE REVISIONS OF THIS LICENSE
- C12 ADDENDUM: How to use this License for your documents
- 5.1 Standard copyright notice
- 5.2 An abstract
- 7.1 Quote
- 8.1 An example of a warning (source)
- 8.2 Example of callouts (source)
- 8.3 Example of callouts (output)
- 8.4 Example of a cross-reference (source)
- 8.5 Example of a cross-reference (output)
- 8.6 Example of an example
- 8.7 Example of an image macro
- 8.8 A typical example of a glossary
- 8.9 Examples of identifiers
- 8.10 Example of an itemized list (source)
- 8.11 Example of an itemized list (output)
- 8.12 Example of an ordered list (source)
- 8.13 Example of an ordered list (output)
- 8.14 Example of a variable list (source)
- 8.15 Example of a variable list (output)
- 8.16 Example of a key
- 8.17 Example of a keyboard combination
- 8.18 Example section outline
- 8.19 Example of a procedure (source)
- 8.20 Single profiling with the attribute
:prof-os: - 8.21 DC file with profiling for SLES
- 8.22 DC file with profiling for SLES
- 8.23 Example of a question and answer section (source)
- 8.24 Example of a table (source)
- 8.25 Example of a table (output)
- 8.26 Example of a single user interface item
- 8.27 Example of nested user interface items
- 9.1 Excerpt from
product-entities.ent - 10.1 Revision history example (source)
- 10.2 Revision history example (output)
Copyright © 2007– 2025 SUSE LLC and contributors. All rights reserved.
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or (at your option) version 1.3; with the Invariant Section being this copyright notice and license. A copy of the license version 1.2 is included in the section entitled “GNU Free Documentation License”.
For SUSE trademarks, see https://www.suse.com/company/legal/. All other third-party trademarks are the property of their respective owners. Trademark symbols (®, ™ etc.) denote trademarks of SUSE and its affiliates. Asterisks (*) denote third-party trademarks.
All information found in this book has been compiled with utmost attention to detail. However, this does not guarantee complete accuracy. Neither SUSE LLC, its affiliates, the authors nor the translators shall be held liable for possible errors or the consequences thereof.