├── .editorconfig ├── .github └── workflows │ └── docbook.yml ├── .gitignore ├── DC-style-guide-adoc ├── DC-style-guide-db ├── LICENSE ├── README.adoc ├── doc-kit.conf ├── prebuilt ├── current │ ├── styleguide_plain.pdf │ └── styleguide_with_changelog.pdf └── old │ ├── opensuse_documentation_styleguide_r115_2010-10-0-13:11.pdf │ ├── styleguide_2014-02-Jun_2015_plain.pdf │ ├── styleguide_2014-02-Jun_2015_with_changelog.pdf │ ├── styleguide_2014-02-plain.pdf │ ├── styleguide_2014-02-with_changelog.pdf │ ├── styleguide_2014-02.1-plain.pdf │ └── styleguide_2014-02.1-with_changelog.pdf └── xml ├── MAIN.styleguide.xml ├── common_copyright_gfdl.xml ├── common_intro_available_doc.xml ├── common_intro_convention.xml ├── common_intro_feedback.xml ├── common_intro_support.xml ├── common_legal.xml ├── common_license_gfdl1.2.xml ├── docu_styleguide.asciidoc.xml ├── docu_styleguide.changes.xml ├── docu_styleguide.content.xml ├── docu_styleguide.contributors.xml ├── docu_styleguide.language.xml ├── docu_styleguide.manage.xml ├── docu_styleguide.name.xml ├── docu_styleguide.outline.xml ├── docu_styleguide.smartdocs.xml ├── docu_styleguide.structure.xml ├── docu_styleguide.taglist.xml ├── docu_styleguide.techwriting.xml ├── docu_styleguide.terminology.xml ├── docu_styleguide.webwriting.xml ├── docu_styleguide.xmlformat.xml ├── generic-entities.ent ├── gfdl.xml ├── legal_suse+gfdl.xml ├── network-entities.ent └── product-entities.ent /.editorconfig: -------------------------------------------------------------------------------- 1 | root = true 2 | [*] 3 | end_of_line = lf 4 | insert_final_newline = false 5 | charset = utf-8 6 | 7 | [*.xml] 8 | indent_style = space 9 | indent_size = 1 10 | max_line_length = 79 11 | trim_trailing_whitespace = true 12 | insert_final_newline = true 13 | 14 | [*.ent] 15 | indent_style = space 16 | indent_size = 4 17 | trim_trailing_whitespace = true 18 | insert_final_newline = true 19 | 20 | [*.adoc] 21 | indent_style = space 22 | indent_size = 2 23 | trim_trailing_whitespace = true 24 | insert_final_newline = true 25 | 26 | [Makefile] 27 | indent_style = tab 28 | -------------------------------------------------------------------------------- /.github/workflows/docbook.yml: -------------------------------------------------------------------------------- 1 | --- 2 | name: Validate/build docs 3 | 4 | on: 5 | push 6 | 7 | jobs: 8 | select-dc-files: 9 | runs-on: ubuntu-latest 10 | outputs: 11 | validate-list: ${{ steps.select-dc-validate.outputs.dc-list }} 12 | build-list: ${{ steps.select-dc-build.outputs.dc-list }} 13 | allow-build: ${{ steps.select-dc-build.outputs.allow-build }} 14 | relevant-branches: ${{ steps.select-dc-build.outputs.relevant-branches }} 15 | steps: 16 | - uses: actions/checkout@v4 17 | 18 | - name: Checking basic soundness of DC files 19 | uses: openSUSE/doc-ci@gha-select-dcs 20 | with: 21 | mode: soundness 22 | 23 | - name: Selecting DC files to validate 24 | id: select-dc-validate 25 | uses: openSUSE/doc-ci@gha-select-dcs 26 | with: 27 | mode: list-validate 28 | 29 | - name: Selecting DC files to build 30 | id: select-dc-build 31 | uses: openSUSE/doc-ci@gha-select-dcs 32 | with: 33 | mode: list-build 34 | original-org: SUSE 35 | 36 | validate: 37 | runs-on: ubuntu-latest 38 | needs: select-dc-files 39 | strategy: 40 | # don't cancel all validation runners when one of them fails, we want full results 41 | fail-fast: false 42 | matrix: 43 | dc-files: ${{ fromJson(needs.select-dc-files.outputs.validate-list) }} 44 | steps: 45 | - uses: actions/checkout@v4 46 | - name: Validating DC file(s) ${{ matrix.dc-files }} 47 | uses: openSUSE/doc-ci@gha-validate 48 | with: 49 | dc-files: ${{ matrix.dc-files }} 50 | 51 | 52 | build-html: 53 | runs-on: ubuntu-latest 54 | needs: [select-dc-files, validate] 55 | if: ${{ needs.select-dc-files.outputs.allow-build == 'true' }} 56 | outputs: 57 | artifact-name: ${{ steps.build-dc.outputs.artifact-name }} 58 | artifact-dir: ${{ steps.build-dc.outputs.artifact-dir }} 59 | strategy: 60 | matrix: 61 | dc-files: ${{ fromJson(needs.select-dc-files.outputs.build-list) }} 62 | steps: 63 | - uses: actions/checkout@v4 64 | - name: Building DC file(s) ${{ matrix.dc-files }} 65 | id: build-dc 66 | uses: openSUSE/doc-ci@gha-build 67 | with: 68 | dc-files: ${{ matrix.dc-files }} 69 | - name: Uploading builds as artifact 70 | uses: actions/upload-artifact@v4 71 | with: 72 | name: ${{ steps.build-dc.outputs.artifact-name }} 73 | path: ${{ steps.build-dc.outputs.artifact-dir }}/* 74 | retention-days: 3 75 | 76 | 77 | publish: 78 | runs-on: ubuntu-latest 79 | if: ${{ success() }} 80 | needs: [select-dc-files, build-html] 81 | steps: 82 | - name: Downloading all build artifacts 83 | uses: actions/download-artifact@v4 84 | with: 85 | path: artifact-dir 86 | - name: Publishing builds on susedoc.github.io 87 | uses: openSUSE/doc-ci@gha-publish 88 | env: 89 | DEPLOY_KEY: ${{ secrets.DEPLOY_KEY_STYLE }} 90 | with: 91 | artifact-path: artifact-dir 92 | relevant-dirs: ${{ needs.select-dc-files.outputs.relevant-branches }} 93 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | *~ 2 | \#*# 3 | .#* 4 | *.bak 5 | *.orig 6 | *.swp 7 | .directory 8 | build/ 9 | .vscode/ 10 | .idea/ 11 | *.code-workspace 12 | .vimrc 13 | worktree 14 | .worktree 15 | worktrees 16 | .worktrees 17 | -------------------------------------------------------------------------------- /DC-style-guide-adoc: -------------------------------------------------------------------------------- 1 | # Documentation Style Guide without change log appendix 2 | 3 | MAIN="MAIN.styleguide.xml" 4 | DOCBOOK5_RNG_URI="http://www.docbook.org/xml/5.2/rng/docbookxi.rnc" 5 | 6 | STYLEROOT="/usr/share/xml/docbook/stylesheet/suse2022-ns" 7 | PROFCONDITION="guide" 8 | PROFOUTPUTFORMAT="adoc" 9 | #OUTPUTNAME="style-guide" 10 | -------------------------------------------------------------------------------- /DC-style-guide-db: -------------------------------------------------------------------------------- 1 | # Documentation Style Guide without change log appendix 2 | 3 | MAIN="MAIN.styleguide.xml" 4 | DOCBOOK5_RNG_URI="http://www.docbook.org/xml/5.2/rng/docbookxi.rnc" 5 | 6 | STYLEROOT="/usr/share/xml/docbook/stylesheet/suse2022-ns" 7 | PROFCONDITION="guide" 8 | PROFOUTPUTFORMAT="db" 9 | #OUTPUTNAME="style-guide" 10 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | xml/gfdl.xml -------------------------------------------------------------------------------- /README.adoc: -------------------------------------------------------------------------------- 1 | = SUSE Documentation Style Guide 2 | 3 | This style guide provides answers to writing, style, and layout questions commonly 4 | arising when editing SUSE documentation. The markup reference at the end of 5 | the guide will help you choose the right XML element for your 6 | purpose. Following this guide will make your documentation more understandable 7 | and easier to translate. 8 | 9 | The Style Guide is published at 10 | https://doc.suse.com/style/current/[doc.suse.com/style]. 11 | 12 | 13 | Contributing 14 | ------------- 15 | 16 | To contribute, send pull requests. Use the `main` branch as the basis for 17 | feature branches. 18 | -------------------------------------------------------------------------------- /doc-kit.conf: -------------------------------------------------------------------------------- 1 | type: docbook5-book 2 | variant: license-gfdl 3 | 4 | file: ff3dfe8d7e05c08517d1b055b278bbc9f7e0aa01 .gitignore 5 | file: c6b4745307e90c9b88905b434cbbaddc54e4541b .editorconfig 6 | file: 08d75fa8f86fa0d912c579d5dbb9a3919c7dc032 xml/generic-entities.ent 7 | file: a79a3bc929478668955564bab48aecc8502555f6 xml/network-entities.ent 8 | file: d222094c8b9b06e37af73e5b91d1231e7c3b46c1 xml/common_intro_available_doc.xml 9 | file: ee8dbf17324e3e72b54bcb6fcc5dec7f7e4e1e9b xml/common_intro_support.xml 10 | file: a54e57381de2312c0bf2df87be5f02c0f96e010c xml/common_intro_convention.xml 11 | file: 825d1d18a1a185ea02785739d9f9d442dd51af09 xml/common_intro_feedback.xml 12 | file: 9f5f8165bfa8b076d80107d811b89c6c6bded8dd xml/common_copyright_gfdl.xml 13 | file: 7022e7485da1b892ea57faf858857981eb3644bc xml/common_legal.xml 14 | file: 58a687a6b796c73ec9716f56b2530e52aea24a6c xml/common_license_gfdl1.2.xml 15 | -------------------------------------------------------------------------------- /prebuilt/current/styleguide_plain.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SUSE/doc-styleguide/ac80dfbde195ed4e9c85cd1df55150fa18ebdce5/prebuilt/current/styleguide_plain.pdf -------------------------------------------------------------------------------- /prebuilt/current/styleguide_with_changelog.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SUSE/doc-styleguide/ac80dfbde195ed4e9c85cd1df55150fa18ebdce5/prebuilt/current/styleguide_with_changelog.pdf -------------------------------------------------------------------------------- /prebuilt/old/opensuse_documentation_styleguide_r115_2010-10-0-13:11.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SUSE/doc-styleguide/ac80dfbde195ed4e9c85cd1df55150fa18ebdce5/prebuilt/old/opensuse_documentation_styleguide_r115_2010-10-0-13:11.pdf -------------------------------------------------------------------------------- /prebuilt/old/styleguide_2014-02-Jun_2015_plain.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SUSE/doc-styleguide/ac80dfbde195ed4e9c85cd1df55150fa18ebdce5/prebuilt/old/styleguide_2014-02-Jun_2015_plain.pdf -------------------------------------------------------------------------------- /prebuilt/old/styleguide_2014-02-Jun_2015_with_changelog.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SUSE/doc-styleguide/ac80dfbde195ed4e9c85cd1df55150fa18ebdce5/prebuilt/old/styleguide_2014-02-Jun_2015_with_changelog.pdf -------------------------------------------------------------------------------- /prebuilt/old/styleguide_2014-02-plain.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SUSE/doc-styleguide/ac80dfbde195ed4e9c85cd1df55150fa18ebdce5/prebuilt/old/styleguide_2014-02-plain.pdf -------------------------------------------------------------------------------- /prebuilt/old/styleguide_2014-02-with_changelog.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SUSE/doc-styleguide/ac80dfbde195ed4e9c85cd1df55150fa18ebdce5/prebuilt/old/styleguide_2014-02-with_changelog.pdf -------------------------------------------------------------------------------- /prebuilt/old/styleguide_2014-02.1-plain.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SUSE/doc-styleguide/ac80dfbde195ed4e9c85cd1df55150fa18ebdce5/prebuilt/old/styleguide_2014-02.1-plain.pdf -------------------------------------------------------------------------------- /prebuilt/old/styleguide_2014-02.1-with_changelog.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SUSE/doc-styleguide/ac80dfbde195ed4e9c85cd1df55150fa18ebdce5/prebuilt/old/styleguide_2014-02.1-with_changelog.pdf -------------------------------------------------------------------------------- /xml/MAIN.styleguide.xml: -------------------------------------------------------------------------------- 1 | 2 | 5 | 8 | %entities; 9 | ]> 10 | 16 | &productname; 17 | 18 | 19 | 20 | 21 | SUSE Documentation Style Guide 22 | This guide provides answers to writing, 23 | style and layout questions for creating effective and consistent documentation for 24 | SUSE products. 25 | 26 | Writing, style and layout for SUSE docs 27 | &productnumber; 28 | 29 | 30 | 31 | 32 | 33 | 34 | https://github.com/SUSE/doc-styleguide/issues/new 35 | via-report-link 36 | 37 | 38 | 39 | 40 | 41 | This guide provides answers to writing, style and layout questions 42 | commonly arising when editing SUSE documentation. The 43 | GeekoDoc, DocBook and AsciiDoc 45 | markup reference in this guide will help you choose the right 46 | formatting options for your purpose. Following this guide will make your 47 | documentation more understandable and easier to translate. 48 | 49 | 50 | 51 | 52 | 53 | 54 | 55 | 56 | 57 | 58 | 59 | 60 | 61 | 62 | 63 | 64 | 65 | 66 | 67 | -------------------------------------------------------------------------------- /xml/common_copyright_gfdl.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 8 | 11 | %entities; 12 | ]> 13 | 14 | 18 | 19 | 20 | yes 21 | 22 | 23 | 24 | Copyright © ©rightstart;– 25 | ©rightholder; and contributors. All rights reserved. 26 | 27 | 28 | Permission is granted to copy, distribute and/or modify this document under 29 | the terms of the GNU Free Documentation License, Version 1.2 or (at your 30 | option) version 1.3; with the Invariant Section being this copyright notice 31 | and license. A copy of the license version 1.2 is included in the section 32 | entitled GNU Free Documentation License. 33 | 34 | 35 | For &suse; trademarks, see 36 | . All 37 | third-party trademarks are the property of their respective owners. Trademark 38 | symbols (®, ™ etc.) denote trademarks of &suse; and its affiliates. 39 | Asterisks (&thrdmrk;) denote third-party trademarks. 40 | 41 | 42 | All information found in this book has been compiled with utmost attention to 43 | detail. However, this does not guarantee complete accuracy. Neither 44 | ©rightholder;, its affiliates, the authors nor the translators shall be 45 | held liable for possible errors or the consequences thereof. 46 | 47 | 48 | -------------------------------------------------------------------------------- /xml/common_intro_available_doc.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 8 | 11 | %entities; 12 | ]> 13 | 17 | Available documentation 18 | 19 | 20 | 21 | yes 22 | 23 | 24 | 25 | 26 | 27 | Online documentation 28 | 29 | 30 | Our documentation is available online at . 33 | Browse or download the documentation in various formats. 34 | 35 | 36 | Latest updates 37 | 38 | The latest updates are usually available in the English-language version of this documentation. 39 | 40 | 41 | 42 | 43 | 44 | &suse; Knowledgebase 45 | 46 | 47 | 48 | If you run into an issue, check out the Technical Information 49 | Documents (TIDs) that are available online at . 50 | Search the &suse; Knowledgebase for known solutions driven by customer need. 51 | 52 | 53 | 54 | 55 | Release notes 56 | 57 | 58 | For release notes, see 59 | . 60 | 61 | 62 | 63 | 64 | On your system 65 | 66 | 67 | For offline use, the release notes are also available under 68 | /usr/share/doc/release-notes on your system. 69 | The documentation for individual packages is available at 70 | /usr/share/doc/packages. 71 | 72 | 73 | Many commands are also described in their manual 74 | pages. To view them, run man, followed 75 | by a specific command name. If the man command is 76 | not installed on your system, install it with sudo zypper 77 | install man. 78 | 79 | 80 | 81 | 82 | 83 | -------------------------------------------------------------------------------- /xml/common_intro_convention.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 8 | %entities; 9 | ]> 10 | 11 | 15 | Documentation conventions 16 | 17 | 18 | 19 | yes 20 | 21 | 22 | 23 | The following notices and typographic conventions are used in this 24 | document: 25 | 26 | 27 | 28 | 29 | 30 | /etc/passwd: Directory names and file names 31 | 32 | 33 | 34 | 35 | PLACEHOLDER: Replace 36 | PLACEHOLDER with the actual value 37 | 38 | 39 | 40 | 41 | PATH: An environment variable 42 | 43 | 44 | 45 | 46 | ls, : Commands, options and 47 | parameters 48 | 49 | 50 | 51 | 52 | user: The name of a user or group 53 | 54 | 55 | 56 | 57 | package_name: The name of a software package 58 | 59 | 60 | 61 | 62 | , 63 | F1 : A key to press or a key combination. Keys 64 | are shown in uppercase, as on a keyboard. 65 | 66 | 67 | 68 | 69 | File, File Save 70 | As : Menu items, buttons 71 | 72 | 73 | 74 | 75 | This paragraph is only relevant for the &x86-64; architectures. The 76 | arrows mark the beginning and the end of the text block. 77 | 78 | 79 | This paragraph is only relevant for the architectures 80 | &zseries; and &power;. The arrows 81 | mark the beginning and the end of the text block. 82 | 83 | 84 | 85 | 86 | Chapter 1, Example chapter: 87 | A cross-reference to another chapter in this guide. 88 | 89 | 90 | 91 | 92 | Commands that must be run with &rootuser; privileges. You can also 93 | prefix these commands with the sudo command to run them 94 | as a non-privileged user: 95 | 96 | &prompt.root;command 97 | &prompt.sudo;command 98 | 99 | 100 | 101 | Commands that can be run by non-privileged users: 102 | 103 | &prompt.user;command 104 | 105 | 106 | 107 | Commands can be split into two or multiple lines by a backslash character 108 | (\) at the end of a line. The backslash informs the shell that 109 | the command invocation will continue after the end of the line: 110 | 111 | &prompt.user;echo a b \ 112 | c d 113 | 114 | 115 | 116 | A code block that shows both the command (preceded by a prompt) 117 | and the respective output returned by the shell: 118 | 119 | &prompt.user;command 120 | output 121 | 122 | 123 | 124 | Notices 125 | 126 | 127 | Warning notice 128 | 129 | Vital information you must know before proceeding. Warns you about 130 | security issues, potential loss of data, damage to hardware, or physical 131 | hazards. 132 | 133 | 134 | 135 | Important notice 136 | 137 | Important information you should know before proceeding. 138 | 139 | 140 | 141 | Note notice 142 | 143 | Additional information, for example about differences in software 144 | versions. 145 | 146 | 147 | 148 | Tip notice 149 | 150 | Helpful information, like a guideline or a piece of practical advice. 151 | 152 | 153 | 154 | 155 | 156 | Compact Notices 157 | 158 | 159 | 160 | Additional information, for example, about differences in software 161 | versions. 162 | 163 | 164 | 165 | 166 | Helpful information, like a guideline or a piece of practical advice. 167 | 168 | 169 | 170 | 171 | 172 | -------------------------------------------------------------------------------- /xml/common_intro_feedback.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 8 | %entities; 9 | ]> 10 | 11 | 15 | Improving the documentation 16 | 17 | 18 | 19 | yes 20 | 21 | 22 | 23 | 24 | Your feedback and contributions to this documentation are welcome. 25 | The following channels for giving feedback are available: 26 | 27 | 28 | 29 | 30 | Service requests and support 31 | 32 | 33 | For services and support options available for your product, see 34 | . 35 | 36 | 37 | To open a service request, you need a &suse; subscription registered at 38 | &scc;. 39 | Go to , log 40 | in and click Create New. 41 | 42 | 43 | 44 | 45 | Bug reports 46 | 47 | 48 | Report issues with the documentation at . 51 | 52 | 53 | To simplify this process, click the Report 54 | an issue icon next to a headline in the HTML 55 | version of this document. This preselects the right product and 56 | category in Bugzilla and adds a link to the current section. 57 | You can start typing your bug report right away. 58 | 59 | 60 | A Bugzilla account is required. 61 | 62 | 63 | 64 | 65 | Contributions 66 | 67 | 68 | To contribute to this documentation, click the Edit source 69 | document icon next to a headline in the HTML version of 70 | this document. This will take you to the source code on GitHub, where you 71 | can open a pull request. 72 | 73 | A GitHub account is required. 74 | 75 | 76 | <guimenu>Edit source document</guimenu> only available for English 77 | 78 | The Edit source document icons are only available for the 79 | English version of each document. For all other languages, use the 80 | Report an issue icons instead. 81 | 82 | 83 | 84 | For more information about the documentation environment used for this 85 | documentation, see the repository's README. 86 | 87 | 88 | 89 | 90 | Mail 91 | 92 | 93 | You can also report errors and send feedback concerning the 94 | documentation to doc-team@suse.com. Include the 95 | document title, the product version, and the publication date of the 96 | document. Additionally, include the relevant section number and title (or 97 | provide the URL) and provide a concise description of the problem. 98 | 99 | 100 | 101 | 102 | Beta program requests 103 | 104 | 105 | &suse; Beta Software is bound by the &suse; Beta EULA. 106 | This EULA is shipped with the software and can also be read 107 | at . 108 | &suse; can only provide support via the Beta Program Channel. 109 | 110 | 111 | To open a bug report, follow the instructions on the appropriate 112 | product page under . 113 | For enhancement requests or any other inquiries, contact us via the 114 | product-specific public beta mailing lists. They are listed at 115 | . 116 | For private requests, contact us directly via 117 | . 118 | 119 | 120 | 121 | 122 | Help 123 | 124 | 125 | If you need further help on &productname;, see 126 | . 127 | 128 | 129 | 130 | 131 | 132 | -------------------------------------------------------------------------------- /xml/common_intro_support.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 8 | %entities; 9 | ]> 10 | 11 | 15 | Support 16 | 17 | 18 | 19 | yes 20 | 21 | 22 | 23 | 24 | Find the support statement for &productname; and general information about 25 | technology previews below. 26 | For details about the product lifecycle, see 27 | . 28 | 29 | For the virtualization support status, see . 31 | 32 | 33 | If you are entitled to support, find details on how to collect information 34 | for a support ticket at 35 | . 36 | 37 | 38 | 39 | Support statement for &productname; 40 | 41 | To receive support, you need an appropriate subscription with &suse;. 42 | To view the specific support offers available to you, go to 43 | and select your product. 44 | 45 | 46 | The support levels are defined as follows: 47 | 48 | 49 | 50 | L1 51 | 52 | 53 | Problem determination, which means technical support designed to provide 54 | compatibility information, usage support, ongoing maintenance, 55 | information gathering and basic troubleshooting using available 56 | documentation. 57 | 58 | 59 | 60 | 61 | L2 62 | 63 | 64 | Problem isolation, which means technical support designed to analyze 65 | data, reproduce customer problems, isolate a problem area and provide a 66 | resolution for problems not resolved by Level 1 or prepare for 67 | Level 3. 68 | 69 | 70 | 71 | 72 | L3 73 | 74 | 75 | Problem resolution, which means technical support designed to resolve 76 | problems by engaging engineering to resolve product defects which have 77 | been identified by Level 2 Support. 78 | 79 | 80 | 81 | 82 | 83 | For contracted customers and partners, &productname; is delivered with L3 84 | support for all packages, except for the following: 85 | 86 | 87 | 88 | 89 | Technology previews. 90 | 91 | 92 | 93 | 94 | Sound, graphics, fonts, and artwork. 95 | 96 | 97 | 98 | 99 | Packages that require an additional customer contract. 100 | 101 | 102 | 103 | 104 | Some packages shipped as part of the module Workstation 105 | Extension are L2-supported only. 106 | 107 | 108 | 109 | 110 | Packages with names ending in -devel (containing header 111 | files and similar developer resources) will only be supported together 112 | with their main packages. 113 | 114 | 115 | 116 | 117 | &suse; will only support the usage of original packages. 118 | That is, packages that are unchanged and not recompiled. 119 | 120 | 121 | 122 | 123 | Technology previews 124 | 125 | Technology previews are packages, stacks, or features delivered by &suse; 126 | to provide glimpses into upcoming innovations. 127 | Technology previews are included for your convenience to give you a chance 128 | to test new technologies within your environment. 129 | We would appreciate your feedback. 130 | If you test a technology preview, please contact your &suse; representative 131 | and let them know about your experience and use cases. 132 | Your input is helpful for future development. 133 | 134 | 135 | Technology previews have the following limitations: 136 | 137 | 138 | 139 | 140 | Technology previews are still in development. 141 | Therefore, they may be functionally incomplete, unstable, or otherwise 142 | not suitable for production use. 143 | 144 | 145 | 146 | 147 | Technology previews are not supported. 148 | 149 | 150 | 151 | 152 | Technology previews may only be available for specific hardware 153 | architectures. 154 | 155 | 156 | 157 | 158 | Details and functionality of technology previews are subject to change. 159 | As a result, upgrading to subsequent releases of a technology preview may 160 | be impossible and require a fresh installation. 161 | 162 | 163 | 164 | 165 | &suse; may discover that a preview does not meet customer or market needs, 166 | or does not comply with enterprise standards. 167 | Technology previews can be removed from a product at any time. 168 | &suse; does not commit to providing a supported version of such 169 | technologies in the future. 170 | 171 | 172 | 173 | 174 | For an overview of technology previews shipped with your product, see the 175 | release notes at . 176 | 177 | 178 | 179 | -------------------------------------------------------------------------------- /xml/common_legal.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 8 | 11 | %entities; 12 | ]> 13 | 14 | 18 | GNU licenses 19 | 20 | 21 | 22 | no 23 | 24 | 25 | 26 | This appendix contains the GNU Free Documentation License version 1.2. 27 | 28 | 29 | 30 | -------------------------------------------------------------------------------- /xml/common_license_gfdl1.2.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 8 | 11 | %entities; 12 | ]> 13 | 14 | 18 | GNU Free Documentation License 19 | 20 | 21 | 22 | no 23 | 24 | 25 | 26 | 27 | 28 | Copyright (C) 2000, 2001, 2002 Free Software Foundation, Inc. 51 Franklin St, 29 | Fifth Floor, Boston, MA 02110-1301 USA. Everyone is permitted to copy and 30 | distribute verbatim copies of this license document, but changing it is not 31 | allowed. 32 | 33 | 34 | 35 | 0. PREAMBLE 36 | 37 | 38 | 39 | The purpose of this License is to make a manual, textbook, or other 40 | functional and useful document "free" in the sense of freedom: to assure 41 | everyone the effective freedom to copy and redistribute it, with or without 42 | modifying it, either commercially or non-commercially. Secondarily, this 43 | License preserves for the author and publisher a way to get credit for their 44 | work, while not being considered responsible for modifications made by 45 | others. 46 | 47 | 48 | 49 | This License is a kind of "copyleft", which means that derivative works of 50 | the document must themselves be free in the same sense. It complements the 51 | GNU General Public License, which is a copyleft license designed for free 52 | software. 53 | 54 | 55 | 56 | We have designed this License to use it for manuals for free software, 57 | because free software needs free documentation: a free program should come 58 | with manuals providing the same freedoms that the software does. But this 59 | License is not limited to software manuals; it can be used for any textual 60 | work, regardless of subject matter or whether it is published as a printed 61 | book. We recommend this License principally for works whose purpose is 62 | instruction or reference. 63 | 64 | 65 | 66 | 1. APPLICABILITY AND DEFINITIONS 67 | 68 | 69 | 70 | This License applies to any manual or other work, in any medium, that 71 | contains a notice placed by the copyright holder saying it can be distributed 72 | under the terms of this License. Such a notice grants a world-wide, 73 | royalty-free license, unlimited in duration, to use that work under the 74 | conditions stated herein. The "Document", below, refers to any such manual or 75 | work. Any member of the public is a licensee, and is addressed as "you". You 76 | accept the license if you copy, modify or distribute the work in a way 77 | requiring permission under copyright law. 78 | 79 | 80 | 81 | A "Modified Version" of the Document means any work containing the Document 82 | or a portion of it, either copied verbatim, or with modifications and/or 83 | translated into another language. 84 | 85 | 86 | 87 | A "Secondary Section" is a named appendix or a front-matter section of the 88 | Document that deals exclusively with the relationship of the publishers or 89 | authors of the Document to the Document's overall subject (or to related 90 | matters) and contains nothing that could fall directly within that overall 91 | subject. (Thus, if the Document is in part a textbook of mathematics, a 92 | Secondary Section may not explain any mathematics.) The relationship could be 93 | a matter of historical connection with the subject or with related matters, 94 | or of legal, commercial, philosophical, ethical or political position 95 | regarding them. 96 | 97 | 98 | 99 | The "Invariant Sections" are certain Secondary Sections whose titles are 100 | designated, as being those of Invariant Sections, in the notice that says 101 | that the Document is released under this License. If a section does not fit 102 | the above definition of Secondary then it is not allowed to be designated as 103 | Invariant. The Document may contain zero Invariant Sections. If the Document 104 | does not identify any Invariant Sections then there are none. 105 | 106 | 107 | 108 | The "Cover Texts" are certain short passages of text that are listed, as 109 | Front-Cover Texts or Back-Cover Texts, in the notice that says that the 110 | Document is released under this License. A Front-Cover Text may be at most 5 111 | words, and a Back-Cover Text may be at most 25 words. 112 | 113 | 114 | 115 | A "Transparent" copy of the Document means a machine-readable copy, 116 | represented in a format whose specification is available to the general 117 | public, that is suitable for revising the document straightforwardly with 118 | generic text editors or (for images composed of pixels) generic paint 119 | programs or (for drawings) some widely available drawing editor, and that is 120 | suitable for input to text formatters or for automatic translation to a 121 | variety of formats suitable for input to text formatters. A copy made in an 122 | otherwise Transparent file format whose markup, or absence of markup, has 123 | been arranged to thwart or discourage subsequent modification by readers is 124 | not Transparent. An image format is not Transparent if used for any 125 | substantial amount of text. A copy that is not "Transparent" is called 126 | "Opaque". 127 | 128 | 129 | 130 | Examples of suitable formats for Transparent copies include plain ASCII 131 | without markup, Texinfo input format, LaTeX input format, SGML or XML using a 132 | publicly available DTD, and standard-conforming simple HTML, PostScript or 133 | PDF designed for human modification. Examples of transparent image formats 134 | include PNG, XCF and JPG. Opaque formats include proprietary formats that can 135 | be read and edited only by proprietary word processors, SGML or XML for which 136 | the DTD and/or processing tools are not generally available, and the 137 | machine-generated HTML, PostScript or PDF produced by some word processors 138 | for output purposes only. 139 | 140 | 141 | 142 | The "Title Page" means, for a printed book, the title page itself, plus such 143 | following pages as are needed to hold, legibly, the material this License 144 | requires to appear in the title page. For works in formats which do not have 145 | any title page as such, "Title Page" means the text near the most prominent 146 | appearance of the work's title, preceding the beginning of the body of the 147 | text. 148 | 149 | 150 | 151 | A section "Entitled XYZ" means a named subunit of the Document whose title 152 | either is precisely XYZ or contains XYZ in parentheses following text that 153 | translates XYZ in another language. (Here XYZ stands for a specific section 154 | name mentioned below, such as "Acknowledgements", "Dedications", 155 | "Endorsements", or "History".) To "Preserve the Title" of such a section when 156 | you modify the Document means that it remains a section "Entitled XYZ" 157 | according to this definition. 158 | 159 | 160 | 161 | The Document may include Warranty Disclaimers next to the notice which states 162 | that this License applies to the Document. These Warranty Disclaimers are 163 | considered to be included by reference in this License, but only as regards 164 | disclaiming warranties: any other implication that these Warranty Disclaimers 165 | may have is void and has no effect on the meaning of this License. 166 | 167 | 168 | 169 | 2. VERBATIM COPYING 170 | 171 | 172 | 173 | You may copy and distribute the Document in any medium, either commercially 174 | or non-commercially, provided that this License, the copyright notices, and 175 | the license notice saying this License applies to the Document are reproduced 176 | in all copies, and that you add no other conditions whatsoever to those of 177 | this License. You may not use technical measures to obstruct or control the 178 | reading or further copying of the copies you make or distribute. However, you 179 | may accept compensation in exchange for copies. If you distribute a large 180 | enough number of copies you must also follow the conditions in section 3. 181 | 182 | 183 | 184 | You may also lend copies, under the same conditions stated above, and you may 185 | publicly display copies. 186 | 187 | 188 | 189 | 3. COPYING IN QUANTITY 190 | 191 | 192 | 193 | If you publish printed copies (or copies in media that commonly have printed 194 | covers) of the Document, numbering more than 100, and the Document's license 195 | notice requires Cover Texts, you must enclose the copies in covers that 196 | carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the 197 | front cover, and Back-Cover Texts on the back cover. Both covers must also 198 | clearly and legibly identify you as the publisher of these copies. The front 199 | cover must present the full title with all words of the title equally 200 | prominent and visible. You may add other material on the covers in addition. 201 | Copying with changes limited to the covers, as long as they preserve the 202 | title of the Document and satisfy these conditions, can be treated as 203 | verbatim copying in other respects. 204 | 205 | 206 | 207 | If the required texts for either cover are too voluminous to fit legibly, you 208 | should put the first ones listed (as many as fit reasonably) on the actual 209 | cover, and continue the rest onto adjacent pages. 210 | 211 | 212 | 213 | If you publish or distribute Opaque copies of the Document numbering more 214 | than 100, you must either include a machine-readable Transparent copy along 215 | with each Opaque copy, or state in or with each Opaque copy a 216 | computer-network location from which the general network-using public has 217 | access to download using public-standard network protocols a complete 218 | Transparent copy of the Document, free of added material. If you use the 219 | latter option, you must take reasonably prudent steps, when you begin 220 | distribution of Opaque copies in quantity, to ensure that this Transparent 221 | copy will remain thus accessible at the stated location until at least one 222 | year after the last time you distribute an Opaque copy (directly or through 223 | your agents or retailers) of that edition to the public. 224 | 225 | 226 | 227 | It is requested, but not required, that you contact the authors of the 228 | Document well before redistributing any large number of copies, to give them 229 | a chance to provide you with an updated version of the Document. 230 | 231 | 232 | 233 | 4. MODIFICATIONS 234 | 235 | 236 | 237 | You may copy and distribute a Modified Version of the Document under the 238 | conditions of sections 2 and 3 above, provided that you release the Modified 239 | Version under precisely this License, with the Modified Version filling the 240 | role of the Document, thus licensing distribution and modification of the 241 | Modified Version to whoever possesses a copy of it. In addition, you must do 242 | these things in the Modified Version: 243 | 244 | 245 | 246 | 247 | 248 | Use in the Title Page (and on the covers, if any) a title distinct from 249 | that of the Document, and from those of previous versions (which should, if 250 | there were any, be listed in the History section of the Document). You may 251 | use the same title as a previous version if the original publisher of that 252 | version gives permission. 253 | 254 | 255 | 256 | 257 | List on the Title Page, as authors, one or more persons or entities 258 | responsible for authorship of the modifications in the Modified Version, 259 | together with at least five of the principal authors of the Document (all 260 | of its principal authors, if it has fewer than five), unless they release 261 | you from this requirement. 262 | 263 | 264 | 265 | 266 | State on the Title page the name of the publisher of the Modified Version, 267 | as the publisher. 268 | 269 | 270 | 271 | 272 | Preserve all the copyright notices of the Document. 273 | 274 | 275 | 276 | 277 | Add an appropriate copyright notice for your modifications adjacent to the 278 | other copyright notices. 279 | 280 | 281 | 282 | 283 | Include, immediately after the copyright notices, a license notice giving 284 | the public permission to use the Modified Version under the terms of this 285 | License, in the form shown in the Addendum below. 286 | 287 | 288 | 289 | 290 | Preserve in that license notice the full lists of Invariant Sections and 291 | required Cover Texts given in the Document's license notice. 292 | 293 | 294 | 295 | 296 | Include an unaltered copy of this License. 297 | 298 | 299 | 300 | 301 | Preserve the section Entitled "History", Preserve its Title, and add to it 302 | an item stating at least the title, year, new authors, and publisher of the 303 | Modified Version as given on the Title Page. If there is no section 304 | Entitled "History" in the Document, create one stating the title, year, 305 | authors, and publisher of the Document as given on its Title Page, then add 306 | an item describing the Modified Version as stated in the previous sentence. 307 | 308 | 309 | 310 | 311 | Preserve the network location, if any, given in the Document for public 312 | access to a Transparent copy of the Document, and likewise the network 313 | locations given in the Document for previous versions it was based on. 314 | These may be placed in the "History" section. You may omit a network 315 | location for a work that was published at least four years before the 316 | Document itself, or if the original publisher of the version it refers to 317 | gives permission. 318 | 319 | 320 | 321 | 322 | For any section Entitled "Acknowledgements" or "Dedications", Preserve the 323 | Title of the section, and preserve in the section all the substance and 324 | tone of each of the contributor acknowledgements and/or dedications given 325 | therein. 326 | 327 | 328 | 329 | 330 | Preserve all the Invariant Sections of the Document, unaltered in their 331 | text and in their titles. Section numbers or the equivalent are not 332 | considered part of the section titles. 333 | 334 | 335 | 336 | 337 | Delete any section Entitled "Endorsements". Such a section may not be 338 | included in the Modified Version. 339 | 340 | 341 | 342 | 343 | Do not retitle any existing section to be Entitled "Endorsements" or to 344 | conflict in title with any Invariant Section. 345 | 346 | 347 | 348 | 349 | Preserve any Warranty Disclaimers. 350 | 351 | 352 | 353 | 354 | 355 | If the Modified Version includes new front-matter sections or appendices that 356 | qualify as Secondary Sections and contain no material copied from the 357 | Document, you may at your option designate some or all of these sections as 358 | invariant. To do this, add their titles to the list of Invariant Sections in 359 | the Modified Version's license notice. These titles must be distinct from any 360 | other section titles. 361 | 362 | 363 | 364 | You may add a section Entitled "Endorsements", provided it contains nothing 365 | but endorsements of your Modified Version by various parties--for example, 366 | statements of peer review or that the text has been approved by an 367 | organization as the authoritative definition of a standard. 368 | 369 | 370 | 371 | You may add a passage of up to five words as a Front-Cover Text, and a 372 | passage of up to 25 words as a Back-Cover Text, to the end of the list of 373 | Cover Texts in the Modified Version. Only one passage of Front-Cover Text and 374 | one of Back-Cover Text may be added by (or through arrangements made by) any 375 | one entity. If the Document already includes a cover text for the same cover, 376 | previously added by you or by arrangement made by the same entity you are 377 | acting on behalf of, you may not add another; but you may replace the old 378 | one, on explicit permission from the previous publisher that added the old 379 | one. 380 | 381 | 382 | 383 | The author(s) and publisher(s) of the Document do not by this License give 384 | permission to use their names for publicity for or to assert or imply 385 | endorsement of any Modified Version. 386 | 387 | 388 | 389 | 5. COMBINING DOCUMENTS 390 | 391 | 392 | 393 | You may combine the Document with other documents released under this 394 | License, under the terms defined in section 4 above for modified versions, 395 | provided that you include in the combination all of the Invariant Sections of 396 | all of the original documents, unmodified, and list them all as Invariant 397 | Sections of your combined work in its license notice, and that you preserve 398 | all their Warranty Disclaimers. 399 | 400 | 401 | 402 | The combined work need only contain one copy of this License, and multiple 403 | identical Invariant Sections may be replaced with a single copy. If there are 404 | multiple Invariant Sections with the same name but different contents, make 405 | the title of each such section unique by adding at the end of it, in 406 | parentheses, the name of the original author or publisher of that section if 407 | known, or else a unique number. Make the same adjustment to the section 408 | titles in the list of Invariant Sections in the license notice of the 409 | combined work. 410 | 411 | 412 | 413 | In the combination, you must combine any sections Entitled "History" in the 414 | various original documents, forming one section Entitled "History"; likewise 415 | combine any sections Entitled "Acknowledgements", and any sections Entitled 416 | "Dedications". You must delete all sections Entitled "Endorsements". 417 | 418 | 419 | 420 | 6. COLLECTIONS OF DOCUMENTS 421 | 422 | 423 | 424 | You may make a collection consisting of the Document and other documents 425 | released under this License, and replace the individual copies of this 426 | License in the various documents with a single copy that is included in the 427 | collection, provided that you follow the rules of this License for verbatim 428 | copying of each of the documents in all other respects. 429 | 430 | 431 | 432 | You may extract a single document from such a collection, and distribute it 433 | individually under this License, provided you insert a copy of this License 434 | into the extracted document, and follow this License in all other respects 435 | regarding verbatim copying of that document. 436 | 437 | 438 | 439 | 7. AGGREGATION WITH INDEPENDENT WORKS 440 | 441 | 442 | 443 | A compilation of the Document or its derivatives with other separate and 444 | independent documents or works, in or on a volume of a storage or 445 | distribution medium, is called an "aggregate" if the copyright resulting from 446 | the compilation is not used to limit the legal rights of the compilation's 447 | users beyond what the individual works permit. When the Document is included 448 | in an aggregate, this License does not apply to the other works in the 449 | aggregate which are not themselves derivative works of the Document. 450 | 451 | 452 | 453 | If the Cover Text requirement of section 3 is applicable to these copies of 454 | the Document, then if the Document is less than one half of the entire 455 | aggregate, the Document's Cover Texts may be placed on covers that bracket 456 | the Document within the aggregate, or the electronic equivalent of covers if 457 | the Document is in electronic form. Otherwise they must appear on printed 458 | covers that bracket the whole aggregate. 459 | 460 | 461 | 462 | 8. TRANSLATION 463 | 464 | 465 | 466 | Translation is considered a kind of modification, so you may distribute 467 | translations of the Document under the terms of section 4. Replacing 468 | Invariant Sections with translations requires special permission from their 469 | copyright holders, but you may include translations of some or all Invariant 470 | Sections in addition to the original versions of these Invariant Sections. 471 | You may include a translation of this License, and all the license notices in 472 | the Document, and any Warranty Disclaimers, provided that you also include 473 | the original English version of this License and the original versions of 474 | those notices and disclaimers. In case of a disagreement between the 475 | translation and the original version of this License or a notice or 476 | disclaimer, the original version will prevail. 477 | 478 | 479 | 480 | If a section in the Document is Entitled "Acknowledgements", "Dedications", 481 | or "History", the requirement (section 4) to Preserve its Title (section 1) 482 | will typically require changing the actual title. 483 | 484 | 485 | 486 | 9. TERMINATION 487 | 488 | 489 | 490 | You may not copy, modify, sublicense, or distribute the Document except as 491 | expressly provided for under this License. Any other attempt to copy, modify, 492 | sublicense or distribute the Document is void, and will automatically 493 | terminate your rights under this License. However, parties who have received 494 | copies, or rights, from you under this License will not have their licenses 495 | terminated so long as such parties remain in full compliance. 496 | 497 | 498 | 499 | 10. FUTURE REVISIONS OF THIS LICENSE 500 | 501 | 502 | 503 | The Free Software Foundation may publish new, revised versions of the GNU 504 | Free Documentation License from time to time. Such new versions will be 505 | similar in spirit to the present version, but may differ in detail to address 506 | new problems or concerns. See 507 | . 508 | 509 | 510 | 511 | Each version of the License is given a distinguishing version number. If the 512 | Document specifies that a particular numbered version of this License "or any 513 | later version" applies to it, you have the option of following the terms and 514 | conditions either of that specified version or of any later version that has 515 | been published (not as a draft) by the Free Software Foundation. If the 516 | Document does not specify a version number of this License, you may choose 517 | any version ever published (not as a draft) by the Free Software Foundation. 518 | 519 | 520 | 521 | ADDENDUM: How to use this License for your documents 522 | 523 | 524 | Copyright (c) YEAR YOUR NAME. 525 | Permission is granted to copy, distribute and/or modify this document 526 | under the terms of the GNU Free Documentation License, Version 1.2 527 | or any later version published by the Free Software Foundation; 528 | with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. 529 | A copy of the license is included in the section entitled “GNU 530 | Free Documentation License”. 531 | 532 | 533 | If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, 534 | replace the “with...Texts.” line with this: 535 | 536 | 537 | with the Invariant Sections being LIST THEIR TITLES, with the 538 | Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. 539 | 540 | 541 | If you have Invariant Sections without Cover Texts, or some other combination 542 | of the three, merge those two alternatives to suit the situation. 543 | 544 | 545 | 546 | If your document contains nontrivial examples of program code, we recommend 547 | releasing these examples in parallel under your choice of free software 548 | license, such as the GNU General Public License, to permit their use in free 549 | software. 550 | 551 | 552 | -------------------------------------------------------------------------------- /xml/docu_styleguide.asciidoc.xml: -------------------------------------------------------------------------------- 1 | 2 | 5 | %entities; 6 | ]> 7 | 8 | Working with AsciiDoc 9 | 10 | To create documentation in the AsciiDoc format, adhere to the comprehensive 11 | guide at 12 | . 13 | 14 | 15 | We also recommend the guidance on AsciiDoc provided in the 16 | SUSE 17 | Technical Reference Documentation Contributors Guide. 18 | 19 | 20 | The following things are important when working with AsciiDoc: 21 | 22 | 23 | 24 | 25 | Only use formatting that is supported by the AsciiDoctor tool. Ignore 26 | features that are only documented for the outdated 27 | asciidoc (Python) tool. In particular, ignore the 28 | documentation at https://powerman.name. 29 | 30 | 31 | 32 | 33 | 34 | Most recommendations from 35 | 36 | are applicable generally. Some recommendations, however, are specific 37 | to &suse; Manager documentation, in particular: 38 | 39 | 40 | 41 | 42 | The section Images—images need to be 43 | added the same way they are added in other DAPS-based 44 | documentation, under the 45 | images/src/FORMAT 46 | directory of the repo. 47 | 48 | 49 | 50 | 51 | The section Working with Drafts—there 52 | is currently no equivalent standard functionality. 53 | 54 | 55 | 56 | 57 | 58 | 59 | -------------------------------------------------------------------------------- /xml/docu_styleguide.content.xml: -------------------------------------------------------------------------------- 1 | 2 | 5 | %entities; 6 | ]> 7 | 8 | Documentation content 9 | 10 | When selecting what to document, keep to the following guidelines: 11 | 12 | 13 | 14 | 15 | Do not promise future features. Only document features that exist 16 | already or that will be finished before the document is first 17 | published. 18 | 19 | 20 | 21 | 22 | In some cases, it is appropriate to warn of scheduled future changes, 23 | such as feature removals. 24 | 25 | 26 | 27 | 28 | Documentation concerning unsupported features should be an exception. 29 | When documenting an unsupported feature (usually a technology 30 | preview), explain the support status before going into 31 | detail about the feature. 32 | 33 | 34 | 35 | 36 | -------------------------------------------------------------------------------- /xml/docu_styleguide.contributors.xml: -------------------------------------------------------------------------------- 1 | 2 | 5 | %entities; 6 | ]> 7 | 11 | Contributors 12 | 13 | For a list of people who contributed to this document, visit 14 | the 15 | Contributors page of our Git repository. 16 | 17 | 18 | -------------------------------------------------------------------------------- /xml/docu_styleguide.language.xml: -------------------------------------------------------------------------------- 1 | 2 | 5 | %entities; 6 | ]> 7 | 8 | Language 9 | 10 | We write documentation in American English. Where spelling differences exist 11 | between American and British English, use the American English variant. For 12 | verbs ending in either -ise or 13 | -ize (like 14 | localise/localize), use the 15 | -ize variant. 16 | 17 | 18 | When in doubt about the spelling or usage of a word, first see 19 | . If the usage of a word is not regulated 20 | there, use the preferred spelling from 21 | 22 | ( for short). 23 | 24 | 25 | The correct spelling of &suse; product names is listed in the terminology 26 | table () and in the 27 | entitiesattributes 29 | file of the Doc Kit repository at 30 | 32 | . 34 | If a product name is not listed in either spot, refer to the official &suse; 35 | Products page and 36 | the Marketing department. Make sure to not use articles in front of product 37 | names. 38 | 39 | 40 | When in doubt about a style rule, see The Chicago Manual of 41 | Style, 15th Edition. 42 | 43 |
44 | Abbreviations 45 | 46 | Avoid using abbreviations, especially unusual ones. Avoid creating plurals 47 | of abbreviations, unless the abbreviation is an acronym or initialism. 48 | 49 |
50 | Acronyms 51 | 52 | Introduce acronyms by providing the expansion in parentheses after the 53 | acronym. Sometimes chapters and parts are used across multiple 54 | documents. Therefore, provide the expansion of an acronym at least once 55 | per chapter. 56 | 57 | 58 | However, do not use headlines to introduce an acronym. Headlines or 59 | captions must not contain both an acronym and its expansion. If a term 60 | is commonly written as an acronym, use the acronym in the title. When 61 | mentioning the term for the first time in the following text, use its 62 | expanded form. All following occurrences of the term in this chapter 63 | should then use the acronym. 64 | 65 | 66 | Create plural forms of acronyms by adding a lowercase s. 67 | For example, use CDs and BIOSes. Never add 68 | an apostrophe before the s or es. 69 | 70 | 71 | For clarity, avoid using possessive forms of acronyms. For example, do 72 | not use XMLʼs specification. 73 | 74 |
75 |
76 | Latin abbreviations 77 | 78 | Do not use Latin abbreviations. Use the full English form: for example, 79 | use that is instead of i.e.. As an 80 | exception to this rule, the abbreviation etc. is 81 | allowed. 82 | 83 |
84 |
85 | Units of measurement 86 | 87 | You may use abbreviations of common units of measurement. For more 88 | information about units of measurement, see 89 | . 90 | 91 |
92 |
93 |
94 | Biases and inclusiveness 95 | 96 | Do not artificially limit your audience by excluding or offending members 97 | of it. 98 | 99 | 100 | Avoid indicating gender in your documentation. If possible, use plural to 101 | allow use of they as the pronoun. Otherwise, use he 102 | or she. 103 | 104 | 105 | &suse; supports the Inclusive Naming Initiative which aims to help avoid 106 | harmful language. When making language choices for documentation, check 107 | the initiative's 108 | Evaluation 109 | Framework and its Word lists. 110 | 111 | 112 | The &suse; official terminology database, 113 | TermWeb, also contains 114 | inclusive naming recommendations. 115 | 116 | 117 | For more information about avoiding gender bias, see The 118 | Chicago Manual of Style, 5.43. For information about names of 119 | example items, see . 120 | 121 |
122 |
123 | Capitalization of headings and titles 124 |
125 | Most titles: sentence-style capitalization 126 | 127 | Sentence-style capitalization is the most common capitalization used in 128 | &suse; documentation. When using sentence-style capitalization, only 129 | proper nouns and the first letter of the first word of a phrase are 130 | capitalized. Apply sentence-style capitalization to all running text and 131 | all types of headings and titles that are part of the document content. 132 | An example for sentence-style capitalization is Ceph core 133 | components. 134 | 135 |
136 |
137 | Document titles: title-style capitalization 138 | 139 | For document titles, such as book, article, and set titles, use 140 | title-style capitalization. This capitalization style is explained in 141 | The Chicago Manual of Style, 8.167. A simplified 142 | version of these rules is below: 143 | 144 | 145 | 146 | 147 | Capitalize the first and the last word. 148 | 149 | 150 | 151 | 152 | Write articles in lowercase. Articles are: the, 153 | a, and an. 154 | 155 | 156 | 157 | 158 | Write prepositions in lowercase unless they are used with a verb 159 | (Logging In) or in a noun (The On 160 | Button). Prepositions are, for example: 161 | up, in, 162 | of, through, and 163 | between. 164 | 165 | 166 | 167 | 168 | Write certain conjunctions in lowercase: and, 169 | but, for, 170 | nor, and or. 171 | 172 | 173 | 174 | 175 | Write as and to in 176 | lowercase. 177 | 178 | 179 | 180 | 181 | Capitalize everything that is not mentioned above. 182 | 183 | 184 | 185 | 186 | Examples for title-style capitalization are Deployment 187 | Guide (book title) or Kernel Module Packages for 188 | SUSE-Based Distributions (article title). 189 | 190 |
191 |
192 |
193 | Colons 194 | 195 | Capitalize the first word after a colon only if it is a proper noun or the 196 | start of a complete sentence. For example: Error message: The 197 | system could not connect to the server. But: Server roles: 198 | file server, Web server and database server. 199 | 200 |
201 |
202 | Commas 203 | 204 | Use commas to separate elements in a series of three or more elements, but 205 | do not put a comma before the conjunction in most simple series. For 206 | example, Find basic information about how to register your system, 207 | modules and extensions. Use commas around phrases like 208 | for example and that is. 209 | Introductory phrases at the beginning of a sentence are normally followed 210 | by a comma. For example, Before using YaST Online Update, configure 211 | a network connection. 212 | 213 |
214 |
215 | Contractions 216 | 217 | Do not use contractions (such as don't), unless you are 218 | purposefully writing a casual document. 219 | 220 |
221 |
222 | Dashes 223 | 224 | Use en dashes (–) between numbers in a range in tables and figures. 225 | 226 | 227 | For punctuation, use em dashes (—). Do not surround em dashes with 228 | spaces. Use em dashes sparingly. 229 | 230 |
231 |
232 | End of sentence punctuation 233 | 234 | End sentences in a period. Avoid using exclamation marks. Restrict 235 | question marks to question and answer sections. 236 | 237 |
238 |
239 | File and directory names 240 | 241 | Under Linux, objects like directories, printers, or flash drives are all 242 | considered files. Therefore, the naming and markup conventions are the 243 | same for drives (for example, hard disks, CD-ROM drives), 244 | directories, or files. 245 | 246 | 247 | The layout for file names and directory names is the same. See the 248 | following example: 249 | 250 | 251 | 252 | 253 | In general, use forward slashes (/) to separate 254 | nested directory or file names. If you are describing actions 255 | performed on Windows&thrdmrk; systems and within a Windows-native file 256 | system, use backward slashes (\) instead. 257 | 258 | 259 | 260 | 261 | In general, when giving absolute paths, always start with a leading 262 | slash to indicate the root of the file system. If you are describing 263 | actions performed on Windows systems and within a Windows-native file 264 | system, do not add a leading slash to absolute paths. 265 | 266 | 267 | 268 | 269 | When referencing a directory name, add a trailing slash. This helps 270 | distinguish between directory names (for example, 271 | /etc/YaST2/) and file names (for example, 272 | /etc/YaST2/control.xml). For less experienced 273 | Linux users, it might be helpful to specify in the running text if it 274 | is a file, device, or directory. For example: In the 275 | /etc/hosts/ directory, do the following. 276 | 277 | 278 | 279 | 280 | Most Linux file systems are case-sensitive. Use capitals exactly as they 281 | appear in the file system. For more information about markup aspects, see 282 | and 283 | . 284 | 285 | 286 | When it is necessary to refer to file extensions, such as in compound 287 | words like PDF file, always capitalize the extension. 288 | 289 |
290 |
291 | Headings 292 | 293 | When writing a descriptive section, use a noun-based heading title, for 294 | example, Concepts of Software. When writing a 295 | task-orientated section, use a verb in gerund, for example, 296 | Installing Software. 297 | 298 | 299 | Keep headings short and simple. Do not use both an acronym and the 300 | expanded form in a heading. Make sure that headlines in a chapter follow 301 | the same pattern. 302 | 303 | 304 | For advice on how to nest sections, refer to 305 | . 306 | 307 |
308 |
309 | Hyphens 310 | 311 | Generally, hyphens are used as joiners for two or more words that form a 312 | single concept and function together as a compound modifier before the 313 | noun. If the noun comes first, the hyphen is not added. For example, 314 | the list in the upper-left corner but place the list 315 | in the corner in the upper left. 316 | 317 | 318 | There are technical guidelines to help you choose whether to use or not to 319 | use a hyphen. 320 | 321 | 322 | Add the hyphen when: 323 | 324 | 325 | 326 | 327 | The last letter of the prefix and the first letter of the word are the 328 | same (shell-like). However, double-e combinations 329 | usually do not get a hyphen: preempted, 330 | reelected. 331 | 332 | 333 | 334 | 335 | The words begin with the prefixes self-, 336 | ex- (that is, former), and 337 | all-: self-assigned, 338 | ex-service, all-data. 339 | 340 | 341 | 342 | 343 | Do not use the hyphen when: 344 | 345 | 346 | 347 | 348 | The prefix and the following word start with a consonant 349 | (subpackage). 350 | 351 | 352 | 353 | 354 | The two-word phrase includes the adverb very and 355 | all adverbs ending in -ly: a very good 356 | time, an easily remembered rule. 357 | 358 | 359 | 360 | 361 | Many combinations that are hyphenated before a noun are not hyphenated 362 | when they occur after a noun. For example: This is the up-to-date 363 | version and The calendar is up to date. 364 | 365 |
366 |
367 | Lists 368 | 369 | For information about creating lists, see . 370 | 371 |
372 |
373 | Numbers and measurements 374 | 375 | Write the integers zero through nine as words. Use numerals for all other 376 | numbers. 377 | 378 | 379 | When the unit of a measurement is abbreviated, always use numerals for the 380 | number. In measurements, add a non-breaking space 381 | (nbsp) between the numeral and its 382 | corresponding unit abbreviation. Use the % sign when paired with a number, 383 | with no space. 384 | 385 | 386 | For more information, see The Chicago Manual of 387 | Style 9.6 and 9.16. 388 | 389 |
390 |
391 | Possessives 392 | 393 | Do not use possessives of acronyms and trademarked terms. Avoid 394 | possessives of inanimate objects. 395 | 396 |
397 |
398 | Prefixes 399 | 400 | Add a hyphen after the prefix to prefixed words only if you foresee 401 | misunderstandings. For example, there is a difference in meaning between 402 | recreate and re-create. 403 | 404 | 405 | For more information about using hyphens, see 406 | . 407 | 408 |
409 |
410 | Quotations 411 | 412 | Use quotations to quote from sources, such as books. In all other cases, 413 | do not use quotation marks: 414 | 415 | 416 | 417 | 418 | For computer input, computer output and user interface elements, use 419 | different markup. See also , 420 | , 421 | and . 422 | 423 | 424 | 425 | 426 | Use 427 | emphasisunderscores 429 | _emphasized_phrase_ to call attention to 430 | new words or phrases, for example, using so-called 431 | target units, to use words in a 432 | non-standard way, for example, packages can get in an 433 | orphaned state, and to refer to a word or 434 | term itself, for example, The word 435 | processor came into use around 1910. 436 | 437 | 438 | 439 | 440 | Do not use quotation marks to indicate irony. Avoid irony in technical 441 | writing. See also . 442 | 443 | 444 | 445 | 446 | To create quotations, use the quote element. 447 | This element is easier to localize than hardcoded quotation marks. During 448 | processing, localized quotation marks are added automatically. Avoid using 449 | single quotation marks. 450 | 451 | 452 | The period and the comma always go within the quotation marks, as 453 | illustrated in . The dash, the semicolon, the 454 | colon, the question mark and the exclamation mark go within the quotation 455 | marks when they apply to the quoted matter only. They go outside when they 456 | apply to the whole sentence. 457 | 458 | 459 | Quote 460 | 461 | Suds may froth, the sign reads. 462 | 463 | 464 |
465 |
466 | Semicolons 467 | 468 | Avoid using semicolons to join sentences. You may use semicolons in place 469 | of commas in very complicated series. 470 | 471 |
472 |
473 | Sentence structure 474 | 475 | Form clear and direct sentences with 25 words or less. Avoid complicated 476 | clauses. Make sure that the relationship between subject, verb, and object 477 | is clear. Avoid joining sentences with semicolons. Avoid ending sentences 478 | with prepositions. 479 | 480 | 481 | Avoid using parentheses. Where they are necessary, move them to the end of 482 | the sentence. Never nest parentheses. 483 | 484 | 485 | Always let the reader know the objective of an action before describing 486 | the action itself. As an example, write: To save the settings, 487 | click OK. 488 | 489 |
490 |
491 | Slashes 492 | 493 | Do not use slashes except when they are part of a standard technical term, 494 | such as TCP/IP or client/server. 495 | Do not add spaces on either side of a forward slash. 496 | 497 |
498 |
499 | Tense 500 | 501 | Use the simple present tense. Apply the simple present tense even to 502 | sentences with if or when clauses and to 503 | prerequisites of an action. For example, If this happens, go 504 | there. or Glibc is installed. 505 | 506 |
507 |
508 | Tone and voice 509 | 510 | Maintain a professional tone. Do not use contractions, except in casual 511 | documents. Do not use humor. Be honest and avoid absolutes and 512 | exaggerations, but focus on positive aspects. 513 | 514 | 515 | Use the second person (you) to refer to the reader. 516 | Normally, the reader is the user or administrator who performs the actions 517 | described. For example, To install all officially released patches 518 | that apply to your system, run zypper patch. Do 519 | not overuse you and your. It is often 520 | implied who you are addressing in the instructions. For example, instead 521 | of Install package on your system, 522 | just say Install package on the 523 | system. 524 | 525 | 526 | Where possible, use active voice. If there is no emphasis on the object of 527 | the verb or if the performer of the action is unknown, use passive voice. 528 | A Samba server must be configured in the network is an 529 | example of the proper use of passive voice. The emphasis is on the server, 530 | not on the person configuring it. 531 | 532 | 533 | When giving a recommendation, start with We recommend. Do 534 | not use passive phrasings like It is recommended. 535 | 536 | 537 | To refer to other parts of the document, start with For more 538 | information (about), see. 539 | 540 |
541 |
542 | Trademarks 543 | 544 | Most products referenced in the documentation are trademarked. Follow 545 | these rules when dealing with these terms: 546 | 547 | 548 | 549 | 550 | Never use trademarks in headings. 551 | 552 | 553 | 554 | 555 | Only use the ®, &tm; or &sm; marks for &suse; products. 556 | 557 | 558 | 559 | 560 | Use an * (asterisk) for all service marks or trademarks of third-party 561 | companies. This acknowledges the service mark or trademark of the 562 | other company. It also protects &suse; if the protection of the brand 563 | changes in any way. 564 | 565 | 566 | 567 | 568 | For more information about markup aspects, see 569 | . 570 | 571 |
572 |
573 | User interface items 574 | 575 | When referring to labels of user interface items, do not include ending 576 | punctuation such as … or :. 577 | Whenever possible, refer to user interface items without identifying them 578 | as any special type of element. For example, use click 579 | OK rather than click the 580 | OK button. However, complex dialogs may require 581 | more specific wording. 582 | 583 | 584 | When referring to UI labels, capitalize them exactly as in the UI itself. 585 | Software created at &suse; (such as YaST or Uyuni) should use 586 | sentence-style capitalization. If it does not, you can make aware the 587 | developers of that software. For more information about sentence-style 588 | capitalization, see and the 589 | &suse; 590 | Product Brand guide. 591 | 592 | 593 | For more information about markup for UI labels, see 594 | . 595 | 596 |
597 | 598 | -------------------------------------------------------------------------------- /xml/docu_styleguide.manage.xml: -------------------------------------------------------------------------------- 1 | 2 | 5 | %entities; 6 | ]> 7 | 8 | Managing documents 9 | 11 | 12 | This section provides an overview over specific features to manage 13 | documents. 14 | 15 |
16 | Remarks 17 | 18 | Use remarks for editorial comments. Remarks can be placed within, before 19 | or after a para but must always be within a section element. When creating 20 | output, remarks can be made visible in the output and thus help within the 21 | editorial process. When creating the final output, deactivate remarks. 22 | 23 | 24 | Start remarks with your user name and the current date, then add a colon 25 | (:) and finally your actual remark. To comment on 26 | someone else's remark, add a new remark directly below it. Delete remarks 27 | when the corresponding issue is resolved. 28 | 29 | <remark>tux (2013-10-13): could not find the option for foo</remark> 30 | <remark>geeko (2013-11-02): see /usr/share/doc/foo.html</remark> 31 | 32 | You can add a role attribute with one of the 33 | following values to show the type of the remark: 34 | 35 | 36 | 37 | 38 | <tag class="attvalue">structure</tag> 39 | 40 | Use this type of remark to suggest changes to the text or XML 41 | structure. 42 | 43 | 44 | 45 | 46 | 47 | <tag class="attvalue">language</tag> 48 | 49 | Use this type of remark to suggest language improvements. 50 | 51 | 52 | 53 | 54 | 55 | <tag class="attvalue">needinfo</tag> 56 | 57 | Use this type of remark to mark sections where you need input from 58 | others, such as developers. 59 | 60 | 61 | 62 | 63 | 64 | <tag class="attvalue">trans</tag> 65 | 66 | Use this type of remark to give hints to translators. 67 | 68 | 69 | 70 | 71 |
72 |
73 | Comments 74 | 75 | Comments can be used for temporarily disabling portions of text. Another 76 | use of comments is to create more permanent internal comments or to mark 77 | up changes made for layout reasons. Comments are never visible in a 78 | publication. 79 | 80 | <!-- This is an XML comment. --> 81 | // This is a single-line comment. 82 | //// 83 | This is a block comment. 84 | It can include multiple lines 85 | //// 86 | 87 | For information about formatting XML comments, see 88 | . 89 | 90 |
91 |
92 | Entities 93 | 94 | Entities (or attributes) are used to expand text. There are several 95 | situations in which they can be used: 96 | 97 | 98 | 99 | 100 | To represent special characters that cannot easily be displayed, 101 | entered or memorized. 102 | 103 | 104 | 105 | 106 | To integrate external files using entities representing references to 107 | their file names. 108 | 109 | 110 | 111 | 112 | To repeat content easily. 113 | 114 | 115 | 116 | 117 | When an entity is defined, it can be used in many places. Entities 118 | increase consistency, as they only need to be defined once and will 119 | automatically be expanded everywhere within the document. 120 | 121 |
122 | Common types of entities 123 | 124 | Official generic entities are maintained in the 125 | Doc Kit 126 | repository. They include &suse; product names and other terms 127 | that are valid for every repository. In repositories configured with Doc 128 | Kit, the file 129 | generic-entities.entgeneric-attributes.adoc 132 | therefore must not be changed (any changes will be overwritten by the 133 | next Doc Kit run). If there is a need to declare a specific entity that 134 | applies to the current repository only, this can be done in the 135 | product-entities.entproduct-attributes.adoc 136 | or entity-decl.ent file in the 137 | respective repository. 138 | 139 | 140 | A 141 | generic-entities.entgeneric-attributes.adoc 144 | or entity-decl.ent file contains several 145 | categories of entities: 146 | 147 | 148 | 149 | Products 150 | 151 | 152 | All &suse; product names and other products and applications. This 153 | helps when sudden name changes are necessary and avoids 154 | misspellings. 155 | 156 | 157 | 158 | 159 | Platforms 160 | 161 | 162 | Use entities for all hardware architectures referenced. This helps 163 | when sudden name changes are necessary. 164 | 165 | 166 | 167 | 168 | Books 169 | 170 | 171 | Title entities for all &suse; books. This helps when sudden name 172 | changes are necessary. 173 | 174 | 175 | 176 | 177 | General Entities 178 | 179 | 180 | Network IP addresses, host names and user names. 181 | 182 | 183 | 184 | 185 | 186 | There are several guidelines to consider when working with product 187 | entities for &suse; documentation: 188 | 189 | 190 | 191 | Entity selection 192 | 193 | 194 | Use the entity name 195 | productname{productname} 198 | to identify the product for which the documentation is built. Set 199 | the value of this entity once per release and have it expand to 200 | the name of the current product: 201 | 202 | &productname; includes 389-ds. 203 | {productname} includes 389-ds. 204 | 205 | If you need to reference a specific subproduct or a different 206 | product, use a more specific entity: 207 | 208 | Tuning &sle; for SAP 209 | Tuning {sle} for SAP 210 | 211 | 212 | 213 | Acronyms 214 | 215 | 216 | In specific cases (for example, limited space in table cells or in 217 | titles), it is acceptable to use an entity for a product name 218 | acronym. Find the approved entities for product name acronyms in 219 | the entity declaration files, such as 220 | product-entities.ent 222 | or 223 | entity-decl.entproduct-attributes.adoc 225 | or 226 | generic-entities.entgeneric-attributes.adoc. 229 | For a product name acronym, you can use the generic entity 230 | productnameshort{productnameshort}. 231 | If you need acronym entities for specific products, they usually 232 | have an appended a at the end, for example, 233 | slsaslsa 234 | for the acronym SLES. 235 | 236 | 237 | 238 | 239 | Trademarks 240 | 241 | 242 | Follow the rules under 243 | and 244 | . 245 | 246 | 247 | 248 | 249 | 250 | If an entity is placed at the beginning of a phrase or title, its 251 | resolved form is usually lowercase (unless specified in uppercase, for 252 | example, for product names). To have it capitalized, use the 253 | phrase role="style:sentencecase" element. 254 | For example: 255 | 256 | <phrase role="style:sentencecase">ulp</phrase> 257 | 258 | The entity ulp expands into User 259 | space live patching. 260 | 261 | 262 | Never add this tag to the content within 263 | command and 264 | systemitem elements. Capitalizing anything 265 | inside these elements makes the content ambiguous. 266 | 267 |
268 |
269 | Using entity files 270 | 271 | &suse; uses a set of custom entities. Find these entities in the 272 | *.ent*-attributes.adoc 273 | files in each documentation repository. One entity file can include 274 | other entity files. 275 | 276 | 277 | 278 | 279 | Entity files are only used for original, English-language documents. 280 | Translated documents contain only the resolved form of entities, 281 | that is, plain-text directly in the document. 282 | 283 | 284 | 285 | 286 | If you need a new entity to be used generically across all 287 | repositories, open a pull request against 288 | generic-entities.entgeneric-attributes.adoc 291 | in the Doc Kit repository. After the change is approved by the Doc 292 | Kit maintainers, the entity update for 293 | generic-entities.entgeneric-attributes.adoc 296 | will be rolled out to all Doc Kit-based repositories with the next 297 | Doc Kit run. If you need a custom entity that only applies to a 298 | specific repository, define it in 299 | product-entities.ent 300 | or entity-decl.ent 301 | product-attributes.adoc in 302 | this specific repository. 303 | 304 | 305 | Do not include custom entity definitions directly in the file 306 | header, unless the custom definitions are needed to override 307 | externally embedded entities. 308 | 309 | 310 | 311 | 312 | Use the UTF-8 encoding when editing and saving the entity 313 | declaration file or any of the &suse; 314 | XMLAsciiDoc 315 | files. 316 | 317 | 318 | 319 | 320 | Each header of a &suse; XML file includes the entity declaration file 321 | (by means of an entity): 322 | 323 | 324 | Entity files are usually included from the book or article main file: 325 | 326 | <!ENTITY % entities SYSTEM "generic-entities.ent"> 327 | %entities; 328 | include::generic-attributes.adoc[] 329 | 330 | Excerpt from <filename>product-entities.ent</filename> 331 | <!ENTITYproduct-sp "1"> 332 | <!ENTITY product-ga "15"> 333 | <!ENTITY productnumber-regurl "&product-ga;.&product-sp;"> 334 | <!ENTITY productnumber "<phrase xmlns='http://docbook.org/ns/docbook' role='productnumber'>15</phrase">"> 335 | :product-sp: 1 336 | :product-ga: 15 337 | :productnumber-regurl: {product-ga;.}{product-sp} 338 | 339 | 340 | 341 | Making an entity declaration. 342 | 343 | 344 | 345 | 346 | Defining the entity name. 347 | 348 | 349 | 350 | 351 | Setting the value which the processed entity should expand to. 352 | 353 | 354 | 355 | 356 | Using another entity within the entity value. This entity 357 | reference is only valid if the other entity is defined somewhere 358 | within the scope of the XML document that is built. However, it 359 | does not matter whether the entity is defined before or after the 360 | current entity definition. 361 | 362 | 363 | 364 | 365 | Using a DocBook/GeekoDoc element within the entity value. The 366 | attribute xmlns must be included to 367 | define the correct XML namespace. 368 | 369 | 370 | 371 | 372 | 373 | 374 | Defining the entity name. 375 | 376 | 377 | 378 | 379 | Setting the value which the processed entity should expand to. 380 | 381 | 382 | 383 | 384 | Using another entity within the entity value. This entity 385 | reference is only valid if the other entity is defined somewhere 386 | within the scope of the XML document that is built. However, it 387 | does not matter whether the entity is defined before or after the 388 | current entity definition. 389 | 390 | 391 | 392 | 393 |
394 |
395 |
396 | Include elements 397 | 398 | Include elements are used to create modular source files that are easier 399 | to work with and can be reused. When editing a book, create a new source 400 | file for every chapter. Later, create a new file that can serve as the 401 | central point. In this file, include elements to reference all chapters in 402 | the correct order: 403 | 404 | <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="gfdl.xml"/> 405 | [appendix] 406 | include::common_license_gfdl1.2.adoc[] 407 | 408 | Include elements allow adding common sections to multiple books or 409 | articles without having to maintain the text in multiple places. Common 410 | sections include licenses and information on typographical conventions. 411 | Includes also simplify co-editing documentation with others in a version 412 | control system as they reduce the chance of merge conflicts. 413 | 414 | 415 | By default, files referenced via XIncludes must be well-formed XML files 416 | that are also valid GeekoDoc fragments. This means that they must have a 417 | single top-level element and must not contain elements that are not 418 | allowed in GeekoDoc. Files that are supposed to be referenced multiple 419 | times from within the same set, book or article must not contain any 420 | xml:id attributes. 421 | 422 | 423 | XIncludes also allow embedding plaintext files, for example, as the 424 | content in screen elements. To embed a 425 | plaintext file, add the attribute 426 | parse="text" to the 427 | xi:include element. 428 | 429 |
430 | 431 | -------------------------------------------------------------------------------- /xml/docu_styleguide.name.xml: -------------------------------------------------------------------------------- 1 | 2 | 5 | %entities; 6 | ]> 7 | 8 | Names of example items 9 | 10 | This section summarizes conventions for creating generic names for objects 11 | in documentation. Most of the following names are covered through entities. 12 | To check their spelling, refer to the Doc Kit repository at 13 | . 14 | See also . 15 | 16 |
17 | Domains 18 | 19 | Use and 20 | as example domains. Both 21 | domains were registered for use in documentation. 22 | 23 |
24 |
25 | Host names 26 | 27 | Use objects of the solar system: For the most important system, use 28 | sun. For other systems, use the names of planets 29 | such as earth or mars. 30 | 31 |
32 |
33 | IPv4 addresses 34 | 35 | Use addresses from the class C subnet 192.168.255.0 36 | for examples. That is, replace the final 0 with any 37 | integer between 0 and 255. To 38 | create examples using a larger setup, use addresses from the private 39 | network ranges. For more information, see 40 | . 41 | 42 |
43 |
44 | IPv6 addresses 45 | 46 | Use addresses from the subnet 2001:0db8::/32 for 47 | examples. That is, after the 2001:0db8: prefix, add 48 | six four-digit numbers, each separated by a colon on both sides. Each of 49 | the hexadecimal digits may have a value between 0 and 50 | f. A valid example URL is 51 | 2001:0db8:0123:4567:89ab:cdef:1234:5678. For more 52 | information, see 53 | . 54 | 55 |
56 |
57 | Users 58 | 59 | For example users, use free-software mascots, such as Tux (Linux Kernel), 60 | Wilber (The GIMP), Geeko (&suse;), Foxkeh (Firefox), Konqi (KDE), or Duke 61 | (Java). 62 | 63 |
64 | 65 | -------------------------------------------------------------------------------- /xml/docu_styleguide.outline.xml: -------------------------------------------------------------------------------- 1 | 2 | 5 | %entities; 6 | ]> 7 | 8 | Outline of a manual 9 | 10 | Maintain a consistent structure within your documents. The structure can 11 | vary between different books, articles or projects, but the most common 12 | parts of the document structure are documented here. 13 | 14 |
15 | Books 16 | 17 | For books, use a document structure that includes the following elements, 18 | in that order: 19 | 20 | 21 | 22 | 23 | a preface 24 | 25 | 26 | 27 | 28 | chapters, split into sections 29 | 30 | 31 | 32 | 33 | (optional) a glossary 34 | 35 | 36 | 37 | 38 | (optional) appendixes 39 | 40 | 41 | 42 | 43 | For books with many chapters, create parts at the outline level above 44 | chapters. 45 | 46 | 47 | 48 | Title page and imprint 49 | 50 | 51 | Both title page and imprint are created automatically, but depend 52 | on information being present in the book. 53 | 54 | 55 | 56 | 57 | Title 58 | 59 | Work with the product manager to define the book title. The 60 | book title should not contain the product name and version. 61 | 62 | 63 | 64 | 65 | 66 | Product name and product version 67 | 68 | Work with the product manager to find the correct product name 69 | and version number. Mark this 70 | information up with 71 | productname and 72 | productnumber, 73 | respectively.Define 74 | :productname: and 75 | :productnumber: attributes to store such 76 | information. 77 | 78 | 79 | 80 | 81 | 82 | Documentation version or revision information 83 | 84 | Optionally, use the releaseinfo 85 | element to mark up version or revision numbers of the 86 | documentation itself. 87 | 88 | 89 | 90 | 91 | 92 | Copyright notice 93 | 94 | Use the standard copyright notice reproduced below. Change 95 | the starting year of the copyright protection to the current 96 | year. 97 | 98 | 99 | 100 | Standard copyright notice 101 | <legalnotice> 102 | <para> 103 | Copyright &copy; [starting year]&ndash;<?dbtimestamp format="Y"?> 104 | SUSE LLC and contributors. All rights reserved. 105 | </para> 106 | <para> 107 | Permission is granted to copy, distribute and/or modify this document 108 | under the terms of the GNU Free Documentation License, Version 1.2 or 109 | (at your option) version 1.3; with the Invariant Section being this 110 | copyright notice and license. A copy of the license version 1.2 is 111 | included in the section entitled <quote>GNU Free Documentation 112 | License</quote>. 113 | </para> 114 | <para> 115 | For &suse; trademarks, see 116 | <link xlink:href="http://www.suse.com/company/legal/"/>. 117 | All other third-party trademarks are the property of their respective 118 | owners. Trademark symbols (&reg;, &trade; etc.) denote trademarks 119 | of &suse; and its affiliates. Asterisks (*) denote third-party 120 | trademarks. 121 | </para> 122 | <para> 123 | All information found in this book has been compiled with utmost 124 | attention to detail. However, this does not guarantee complete 125 | accuracy. Neither SUSE LLC, its affiliates, the authors nor the 126 | translators shall be held liable for possible errors or the 127 | consequences thereof. 128 | </para> 129 | </legalnotice> 130 | 131 | 132 | Standard copyright notice 133 | Copyright (C) {copyrightstart}{ndash}{localdate} {copyrightholder} and 134 | contributors. All rights reserved. 135 | 136 | Permission is granted to copy, distribute and/or modify this document under the 137 | terms of the GNU Free Documentation License, Version 1.2 or (at your option) 138 | version 1.3; with the Invariant section being this copyright notice and license. 139 | A copy of the license version 1.2 is included in the section entitled 'GNU Free 140 | Documentation License'. 141 | 142 | For {suse} trademarks, see https://www.suse.com/company/legal/. All third-party 143 | trademarks are the property of their respective owners. Trademark symbols ((R), 144 | (TM) etc.) denote trademarks of {suse} and its affiliates. Asterisks (*) denote 145 | third-party trademarks. 146 | 147 | All information found in this book has been compiled with utmost attention to 148 | detail. However, this does not guarantee complete accuracy. Neither 149 | {copyrightholder}, its affiliates, the authors nor the translators shall be held 150 | liable for possible errors or the consequences thereof. 151 | 152 | 153 | 154 | 155 | 156 | 157 | Abstract 158 | 159 | 160 | Use an abstract to summarize the information provided in a book, 161 | article, chapter or set in 70–150 characters. Do not use 162 | lists, images or examples in an abstract. 163 | 164 | 165 | An abstract 166 | 167 | Perform an upgrade of a &sle; system to a new major version in 168 | environments which do not allow for standard booting of the 169 | installation. 170 | 171 | 172 | 173 | 174 | 175 | Table of contents 176 | 177 | 178 | The table of contents is generated automatically. 179 | 180 | 181 | 182 | 183 | Preface 184 | 185 | 186 | Include a brief overview of the content of a manual, related 187 | manuals and typographical conventions. The preface can also contain 188 | information about its target audience. 189 | 190 | 191 | 192 | 193 | Parts 194 | 195 | 196 | If you are writing a book with many chapters, create parts at the 197 | outline level above chapters. Parts should contain at least three 198 | chapters. Keep part titles clear and concise. Often a single noun 199 | is enough. Typical part titles are 200 | Installation or Network. 201 | 202 | 203 | 204 | 205 | Chapters 206 | 207 | 208 | Chapter titles should not contain product version numbers which 209 | affect the output of data analytics. Chapters typically consist of 210 | the following elements (appendixes should be regarded an 211 | exception): 212 | 213 | 214 | 215 | 216 | Abstract 217 | 218 | In an abstract, summarize the topic instead of summarizing 219 | the outline. See also 220 | . 222 | cwickert 2021-12-09: The 70–155 chars range is taken from 223 | , 224 | we try to play it safe, thus reducing maximum character count by 5 to just 150. 225 | 226 | 227 | 228 | 229 | 230 | 231 | Introduction 232 | 233 | Provide introductory information directly after the abstract. 234 | Do not place it in a separate section. 235 | 236 | 237 | 238 | 239 | 240 | Sections 241 | 242 | Structure the detailed information, so readers can skim the 243 | text. Create sections for every major task, such as 244 | installing, configuring, monitoring, and administering. If 245 | helpful, split sections into subsections. Avoid nesting 246 | deeper than three levels of sections. 247 | 248 | 249 | 250 | Start sections with an introductory paragraph outlining the 251 | focus of the section. If the section describes a sequential 252 | task, add a procedure description, as discussed in 253 | . Steps of a procedure can 254 | contain a cross-reference to subsections where topical 255 | background is provided and an action is explained in detail. 256 | See also . 257 | 258 | 259 | 260 | 261 | Troubleshooting 262 | 263 | In this section, collect common mistakes and problems. The 264 | section should always be named 265 | Troubleshooting. Use the DocBook element 267 | qandaset[qanda] block (a 269 | Question and Answer 270 | section) to mark up Troubleshooting 271 | problems. In case you want to 272 | describe solutions to more than ten problems, add topical 273 | subsections ( 274 | qandadiv elements) below the 275 | Troubleshooting section. 276 | 277 | 278 | 279 | 280 | 281 | More information 282 | 283 | In a section named More information, 284 | collect Web links to all sources of information that might 285 | prove helpful in a given context. Follow the general 286 | referencing guidelines in 287 | when creating such 288 | sections. 289 | 290 | 291 | 292 | 293 | 294 | 295 | 296 | Glossary 297 | 298 | 299 | The optional glossary contains important terms in alphabetical 300 | order and provides a brief explanation for each. For more 301 | information on creating lists of terms, see 302 | . 303 | 304 | 305 | 306 | 307 | Contributors 308 | 309 | 310 | Writing documentation is a collaborative effort. To give credit to 311 | all contributors, add an appendix to the guides which points to the 312 | Contributors page for the respective GitHub 313 | repository. For an example, see . 314 | 315 | 316 | For articles and small documents (such as &suse; Best Practices) 317 | whose content is created and maintained by five or fewer 318 | contributors, all of whom are from outside the documentation team, 319 | credit the contributors on the title page. 320 | 321 | 322 | The above are a minimum. In addition, make sure that the 323 | contributors appendix is compliant with the document license. 324 | 325 | 326 | 327 | 328 |
329 |
330 | Articles 331 | 332 | For articles, use a document structure that includes the following 333 | elements, in that order: 334 | 335 | 336 | 337 | 338 | introduction 339 | 340 | 341 | 342 | 343 | sections, split into subsections 344 | 345 | 346 | 347 | 348 | (optional) a glossary 349 | 350 | 351 | 352 | 353 | (optional) appendixes 354 | 355 | 356 | 357 |
358 | 359 | -------------------------------------------------------------------------------- /xml/docu_styleguide.smartdocs.xml: -------------------------------------------------------------------------------- 1 | 2 | 5 | %entities; 6 | ]> 7 | 11 | Working with &sd; 12 | 13 | &sd; represent a modular approach to documentation whose goal is producing 14 | sets of adaptable, solution-based, easy-to-find and reusable documents. 15 | 16 | 17 | Rather than covering a complete technology or a set of problems, each &sd; 18 | article serves one distinct purpose. Each article stands for itself, 19 | including requirements, context, instructions, troubleshooting and FAQs. 20 | 21 | 22 | &sd; consist of topics—smaller information units that can be reused 23 | in different contexts. Four different topic types are provided: 24 | 25 | 26 | 27 | 28 | Task topics instruct the user how to perform certain tasks. 29 | 30 | 31 | 32 | 33 | Concept topics explain underlying concepts to the users. 34 | 35 | 36 | 37 | 38 | Reference topics inform the user about basic facts (settings, options, 39 | parameters, etc.). 40 | 41 | 42 | 43 | 44 | Glue topics help navigate complex topics and provide links to related 45 | information (combine texts or structures that do not fit into any other 46 | category). Typical glue topics include For more 47 | information and What's next sections. Use glue 48 | topics to provide an additional layer of navigation for your article. 49 | 50 | 51 | 52 | 53 | Articles are built by bundling these topics into assembly 54 | files—organizational units to structure the topics to create a 55 | coherent and meaningful document. 56 | 57 | 58 | To create a &sd; project, use the templates for the assembly and its 59 | topical components that are provided in the 60 | doc-modular 62 | repository. 63 | 64 |
65 | Using ITS tags with assemblies 66 | 67 | Assembly files use ITS tags and attributes which flag whether the content 68 | of the tag should be translated or not. In the following example, the ITS 69 | attribute indicates that the content of the tag should not be translated: 70 | 71 | <meta name="maintainer" content="Smart Doc author" its:translate="no"/> 72 | 73 | If the its:translate attribute is set to 74 | yes, translation is needed. 75 | 76 | 77 | 78 | 79 | 80 | 81 | 82 | 83 | Element name 84 | Description 85 | Translation 86 | 87 | 88 | 89 | 90 | 91 | 92 | <meta name="bugtracker" its:translate="no"> 93 | 94 | 95 | 96 | &suse;-specific info needed by the doc-manager tool and DAPS to process and build &suse; user documentation. 97 | 98 | 99 | No 100 | 101 | 102 | 103 | 104 | 105 | <phrase role="url">https://bugzilla.suse.com/enter_bug.cgi</phrase> 106 | 107 | 108 | 109 | &suse;-specific info needed by the doc-manager tool and DAPS to process and build &suse; user documentation. 110 | 111 | No 112 | 113 | 114 | 115 | 116 | <phrase role="component">Non-product-specific documentation</phrase> 117 | 118 | 119 | 120 | &suse;-specific info needed by the doc-manager tool and DAPS to process and build &suse; user documentation. 121 | 122 | 123 | No 124 | 125 | 126 | 127 | 128 | 129 | <phrase role="product">&sd;</phrase> 130 | 131 | 132 | 133 | &suse;-specific info needed by the doc-manager tool and DAPS to process and build &suse; user documentation. 134 | 135 | 136 | No 137 | 138 | 139 | 140 | 141 | 142 | <phrase role="assignee">assignee@suse.com</phrase> 143 | 144 | 145 | 146 | &suse;-specific info needed by the doc-manager tool and DAPS to process and build &suse; user documentation. 147 | 148 | 149 | No 150 | 151 | 152 | 153 | 154 | 155 | <meta name="translation" its:translate="no"/> 156 | 157 | 158 | 159 | &suse;-specific info needed by the doc-manager tool and DAPS to process and build &suse; user documentation. 160 | 161 | 162 | 163 | No 164 | 165 | 166 | 167 | 168 | 169 | 170 | <phrase role="trans">yes</phrase> 171 | 172 | 173 | 174 | &suse;-specific info needed by the doc-manager tool and DAPS to process and build &suse; user documentation. 175 | 176 | No 177 | 178 | 179 | 180 | 181 | <phrase role="language">de-de,cs-cz</phrase> 182 | 183 | 184 | &suse;-specific info needed by the doc-manager tool and DAPS to process and build &suse; user documentation. 185 | 186 | No 187 | 188 | 189 | 190 | 191 | <meta name="architecture" content="x86;power" 192 | its:translate="no"/> 193 | 194 | 195 | 196 | &suse;-specific info needed by the doc-manager tool and DAPS to process and build &suse; user documentation. 197 | 198 | No 199 | 200 | 201 | 202 | 203 | <meta name="productname" its:translate="no"/> 204 | 205 | 206 | 207 | The formal name of a product 208 | 209 | No 210 | 211 | 212 | 213 | 214 | <productname version="15-SP5">&sles;</productname> 215 | 216 | 217 | 218 | A number assigned to a product 219 | 220 | No 221 | 222 | 223 | 224 | 225 | <meta name="title" its:translate="yes"> 226 | short title for SEO and social media, max. 55 chars</meta> 227 | 228 | 229 | 230 | SEO-specific info. Adhere to the length limitations. 231 | 232 | 233 | 234 | Yes 235 | 236 | 237 | Stick to the length limitations, min. 29 chars and max. 55 238 | chars 239 | 240 | 241 | 242 | 243 | 244 | 245 | <meta name="description" its:translate="yes"> 246 | short description, max. 150 chars</meta> 247 | 248 | 249 | 250 | SEO-specific info. Adhere to the length limitations. 251 | 252 | 253 | 254 | Yes 255 | 256 | 257 | Stick to the length limitations, max. 150 chars 258 | 259 | 260 | 261 | 262 | 263 | 264 | <meta name="social-descr" its:translate="yes"> 265 | ultrashort description for social media, max. 55 chars</meta> 266 | 267 | 268 | 269 | SEO-specific info. Adhere to the length limitations. 270 | 271 | 272 | 273 | Yes 274 | 275 | 276 | Stick to the length limitations, max. 55 chars 277 | 278 | 279 | 280 | 281 | 282 | 283 | Doc Manager tags: 284 | 285 | 286 | <dm:docmanager xmlns:dm="urn:x-suse:ns:docmanager"> 287 | <dm:bugtracker> 288 | <dm:url>https://bugzilla.suse.com/enter_bug.cgi</dm:url> 289 | <dm:component>Smart Docs</dm:component> 290 | <dm:product>Documentation</dm:product> 291 | <dm:assignee>maintainer@suse.com</dm:assignee> 292 | </dm:bugtracker> 293 | <dm:editurl>https://github.com/SUSE/doc-modular/tree/</dm:editurl> 294 | <dm:translation>no</dm:translation> 295 | </dm:docmanager> 296 | 297 | 298 | info: Wrapper to contain bibliographic 299 | information about the content and other meta info. 300 | dm:PLACEHOLDER: &suse;-specific info needed by 301 | the doc-manager tool and DAPS to process and build &suse; user 302 | documentation. 303 | 304 | No 305 | 306 | 307 | 308 | 309 | Resources: 310 | 311 | 312 | <resource xml:id="_glue-example" href="../glues/glue.xml"> 313 | <description>Glue example</description> 314 | </resource> 315 | 316 | 317 | 318 | &suse;-specific info needed by the doc-manager tool and DAPS to process and build &suse; user documentation. 319 | 320 | 321 | 322 | resourceNo 323 | 324 | 325 | descriptionYes 326 | 327 | 328 | 329 | 330 | 331 | 332 | Merge: 333 | 334 | 335 | <merge> 336 | <title>Your title, limit to 55 characters, if possible</title> 337 | <subtitle>Subtitle if necessary</subtitle> 338 | <revhistory xml:id="rh-USE-ROOTID"> 339 | <revision> 340 | <date>2024-11-11</date> 341 | <revdescription> 342 | <para> 343 | Describe the purpose of this revision 344 | </para> 345 | </revdescription> 346 | </revision> 347 | <revision> 348 | <date>2024-10-10</date> 349 | <revdescription> 350 | <para> 351 | Describe the purpose of this revision 352 | </para> 353 | </revdescription> 354 | </revision> 355 | </revhistory> 356 | <module resourceref="_concept-example" renderas="section"/> 357 | </merge> 358 | <title>You are a very special concept now!</title> 359 | 360 | 361 | 362 | 363 | 364 | titleand 365 | subtitleYes, with length 366 | limitations (see above) 367 | 368 | 369 | revhistoryNo 370 | 371 | 372 | moduleNo 373 | 374 | 375 | titleYes 376 | 377 | 378 | 379 | 380 | 381 | 382 |
383 |
384 | Revision history 385 | 386 | A revision history lists all the high-level changes 387 | about the document itself. It gives the reader an overview of important 388 | changes made over time. 389 | 390 | 391 | Update revision history regularly, mentioning most important changes to 392 | your document when you amend or rework it. The data you enter as revision 393 | history is used as metadata. The Revision history text is 394 | available as a link before the abstract and opens up in its individual 395 | page. Keep in mind the following rules: 396 | 397 | 398 | 399 | 400 | List revision entries in descending order by date. The latest entry 401 | must always come first. 402 | 403 | 404 | 405 | 406 | Describe only significant changes that you performed. 407 | 408 | 409 | 410 | 411 | If you have several changes of the same type (addition, change, 412 | removal), you may group them under a dedicated 413 | itemizedlist. 414 | 415 | 416 | 417 | 418 | Do not add links or references with xref of any kind. If 419 | you want to mention a specific issue, use the abbreviations from 420 | 421 | and wrap it inside the tag uri. 422 | 423 | 424 | 425 | 426 | Revision history example (source) 427 | 428 | <revhistory xml:id="rh-USE-ROOTID"> 429 | <revision><date>YYYY-MM-DD</date> 430 | <revdescription> 431 | <para>Updated CONTENT, extended CONTENT, removed CONTENT</para> 432 | </revdescription> 433 | </revision> 434 | <revision><date>YYYY-MM-DD</date> 435 | <revdescription> 436 | <para>Updated for the initial release of <phrase role="productname">SUSE Linux Enterprise Server</phrase> 437 | <phrase role="productnumber">15 SP6</phrase></para> 438 | </revdescription> 439 | </revision> 440 | </revhistory> 441 | 442 | 443 | Revision history example (output) 444 | 445 | 2024-11-13 446 | 447 | Updated chapter on foo bar, removed section on foo bar 1 448 | 449 | 450 | 2024-09-21 451 | 452 | Updated for the initial release of SUSE Linux Enterprise Server 453 | 15 SP6 454 | 455 | 456 | 457 | 458 |
459 | 460 | -------------------------------------------------------------------------------- /xml/docu_styleguide.techwriting.xml: -------------------------------------------------------------------------------- 1 | 2 | 5 | %entities; 6 | ]> 7 | 8 | Writing technical documentation 9 | 10 | Technical writing has certain characteristics that make it different from 11 | other types of writing. Its objective is to provide readers with complex 12 | information and comprehensive answers they are searching for. The content 13 | should be well-structured, clear and concise. Effective technical 14 | documentation is straightforward, detailed and focused on problem-solving, 15 | and there is a specific workflow for its creation: 16 | 17 | 18 | 19 | Defining the target audience 20 | 21 | 22 | Adjust tone, style and technicality of the text based on the intended 23 | audience. Keep in mind that not all facts that seem obvious to you 24 | will be obvious to your readers. 25 | 26 | 27 | 28 | 29 | Researching a topic 30 | 31 | 32 | Start with research on the information that is relevant to the target 33 | audience. Receive essential input from issue tracking systems like 34 | GitHub, and project management tools. 35 | 36 | 37 | 38 | 39 | Writing about a topic 40 | 41 | 42 | Start writing at an early stage, even if you have not finished your 43 | research yet. Prepare a draft document and discuss it with 44 | subject-matter experts. 45 | 46 | 47 | 48 | 49 | Getting reviews 50 | 51 | 52 | In a first review of your text, identify and fix the most obvious 53 | issues like typos, unfinished sentences, etc. After self-review, ask 54 | for a technical review by dedicated specialists. A technical review 55 | uncovers technical or factual errors like missing or misspelled 56 | package names, wrong commands or forgotten options. 57 | 58 | 59 | Request a peer review which can improve your text and detect any 60 | structural problems or logical traps. You can then do a spell check, 61 | link check and style check with the DAPS tool. 62 | 63 | 64 | Finally, ask for a linguistic review that tackles language issues, 65 | typos, inconsistencies and style guide compliance. 66 | 67 | 68 | 69 | 70 | 71 | For more information on how to produce meaningful content that will rank 72 | high on the Web, see and 73 | . 74 | 75 | 76 | -------------------------------------------------------------------------------- /xml/docu_styleguide.webwriting.xml: -------------------------------------------------------------------------------- 1 | 2 | 5 | %entities; 6 | ]> 7 | 8 | Writing for the Web 9 | 10 | Create engaging and informative content that helps your audience and is 11 | optimized for the Web. 12 | 13 |
14 | Topical structure 15 | 16 | The most important thing to do with your Web copy is to help users get 17 | answers to their questions as soon as possible. To achieve this, we 18 | recommend the modular approach of topic-based authoring where 19 | documentation is created and maintained in chunks, subsequently referred 20 | to as topics. 21 | 22 | 23 | Topics have the sole purpose of supporting users in their tasks. Each 24 | topic focuses on one specific subject and has one distinct purpose. We 25 | write topics in a way that they can stand alone as well as in context 26 | with other topics. They should also be reusable in different contexts. 27 | 28 | 29 | Recommendations: 30 | 31 | 32 | 33 | 34 | Put your most important information first. Users typically decide if 35 | they are going to stay on your page within 3–5 seconds. Make 36 | sure your copy helps users understand the big picture right away. 37 | 38 | 39 | 40 | 41 | Write for scanners. Help readers find the answer to their question. 42 | Create headlines that are clear and to the point. Break long 43 | headlines into a heading and sub-head. Ask yourself: Is it easy to 44 | see the benefit of the page with a quick glance? 45 | 46 | 47 | 48 | 49 | Organize content logically. Layer and break up your content into 50 | sections to help users find answers at a glance. 51 | 52 | 53 | 54 |
55 |
56 | Writing SEO-friendly content 57 | 58 | SEO, or Search Engine Optimization, is the strategy to attract organic 59 | (unpaid) traffic that originates from online search and refers to 60 | visitors landing on the Web site. When it comes to SEO, content is key. 61 | Here are some insights to help you create and design the content that 62 | will rank high in search engines. 63 | 64 | 65 | 66 | Brainstorm and research keywords 67 | 68 | 69 | To learn what type of content search engines deem best for a 70 | specific keyword, search the phrases you want to rank for. Bear in 71 | mind the approved &suse; documentation terminology. 72 | 73 | 74 | At the same time, do not stuff your content with keywords. The 75 | keyword ratio for an article should be 2–4%, that is, 76 | 8–10 keywords per 500 words. 77 | 78 | 79 | 80 | 81 | Structure your content in a way that is easy for users to scan 82 | 83 | 84 | Structuring your headings in a hierarchy can make a larger content 85 | piece easily scannable while helping search engines understand the 86 | context of your content. For example: 87 | 88 | <H1> Dealing with Boot and Installation Problems 89 | <H2> Problems Booting 90 | <H3> Solution 1 91 | <H3> Solution 2 92 | <H2> Problems Installing 93 | <H3> Solution 1 94 | <H3> Solution 2 95 | 96 | 97 | 98 | 99 | Create concise and meaningful title tags and meta descriptions 100 | 101 | 102 | Search engines pull the title tag (meta title) from H1 and the 103 | meta description from the abstract. The number of characters is 104 | limited, and the recommended length for meta titles is 55–65 105 | characters (not shorter than 29), and meta descriptions between 106 | 145–155 characters. Optimize your headings and content by 107 | naturally integrating keywords, such as product names, wherever relevant. 108 | 109 | Place the primary keyword in the page title, the first H1, 110 | the first paragraph, and the URL slug. Use secondary keywords 111 | in H2–H3 headings, image alt text and the meta description to support 112 | discoverability and relevance. 113 | 114 | Product names are known for their extra length, so effective page 115 | titles and meta descriptions may require the use of abbreviations. 116 | From the search engine perspective, it can be helpful to mention 117 | the abbreviation within the content by adding the abbreviation in 118 | parenthesis after the first use of the term. 119 | 120 | 121 | 122 | 123 | Link from (and to) your content 124 | 125 | 126 | Links are critical to establishing the authority and relevance of 127 | your content. The two most important types of links are: 128 | 129 | 130 | 131 | 132 | Internal links lead to and from other pages within the same 133 | domain and help establish the relationship between two pieces 134 | of content. Internal linking helps search engines discover new 135 | pages on the Web site and index them. 136 | 137 | 138 | 139 | 140 | Inbound links lead to your content piece from a different 141 | domain (for example, SAP.com to SUSE.com). 142 | 143 | 144 | 145 | 146 | External links to high-quality, creditable Web sites help increase 147 | the validity of your own Web site. The better the links, the higher 148 | the page ranks in search results. 149 | 150 | 151 | 152 | 153 |
154 |
155 | Ensuring accessibility 156 | 157 | Accessible technical documentation is essential because it ensures 158 | information is available to all users regardless of disabilities or 159 | impairments. Many users rely on assistive technologies such as screen 160 | readers and alternative input devices to navigate Web pages. Additionally, 161 | accessible documentation supports compliance with legal requirements and 162 | makes more online resources usable for everyone. Here are some guidelines 163 | on how to make content more accessible: 164 | 165 | 166 | 167 | Provide alternative text for images 168 | 169 | 170 | Users who rely on screen readers need alternative (alt) text to 171 | understand the purpose of an image. Describe the image’s essential 172 | content and function. For example, instead of screenshot of 173 | settings, say The Settings menu showing the notifications 174 | option turned on. Learn more about alt text markup 175 | in . 176 | 177 | 178 | 179 | 180 | Use clear and simple language 181 | 182 | 183 | Technical documentation should be easy to read and understand. Avoid 184 | unnecessary jargon, use plain language where possible, and keep sentences 185 | concise. This helps non-native speakers and users with cognitive disabilities. 186 | 187 | 188 | 189 | 190 | Ensure tables are readable and well-formatted 191 | 192 | 193 | Tables should be structured so that assistive technologies can 194 | interpret them correctly. Always use table headers for columns 195 | and rows to provide context. Avoid leaving cells empty—if no data 196 | applies, use a placeholder such as N/A or 197 | None. More about tables in . 198 | 199 | 200 | 201 | 202 |
203 | 204 |
205 | Writing for a global audience 206 | 207 | Remember that every document is a potential candidate for localization 208 | (translation). Make sure the document’s original English content is 209 | correct and clear. Simplicity, clarity and direct prose are essential. 210 | 211 | 212 | Recommendations: 213 | 214 | 215 | 216 | 217 | Keep sentences short. Shorter sentences help translators and target 218 | audience to better understand the content. 219 | 220 | 221 | 222 | 223 | Be consistent. Stick to the terminology and use the same sentence 224 | structure for similar content. Use the same sentences for repetitive 225 | texts. This helps to improve the translation memory leverage. 226 | 227 | 228 | 229 | 230 | Use proofreading and review options. Have your content reviewed to 231 | detect misunderstandings in advance. 232 | 233 | 234 | 235 | 236 | Keep it clear. Make clear statements and avoid should, 237 | could and similar unprecise words. 238 | 239 | 240 | 241 | 242 | Mark non-translatable text. Use tags as defined in 243 | or use the ITS tag feature to mark all 244 | content that should not be translated (for more information, see 245 | ). Use entities for product names, 246 | example names, etc. Always mark code as such so that it is not 247 | translated. 248 | 249 | 250 | 251 | 252 | Write for the world (if possible). Do not use country-specific words 253 | and examples. Use common international examples instead. 254 | 255 | 256 | 257 | 258 | Use only as many graphics as needed. As each graphic or screenshot 259 | needs to be localized as well, keep it to the minimum. 260 | 261 | 262 | 263 | 264 | Do not break sentences. Do not use hard breaks within a sentence. 265 | 266 | 267 | 268 | 269 | Do not break your sentence with lists. For example, do not structure 270 | the phrase like this: 271 | 272 | You can use the following commands: 273 | -a 274 | -z 275 | -b 276 | to start the system update. 277 | 278 | 279 | Keep the sentence together instead: 280 | 281 | 282 | To start the system update, you can use the following commands: 283 | -a 284 | -z 285 | -b 286 | 287 | 288 | 289 |
290 | 291 | -------------------------------------------------------------------------------- /xml/docu_styleguide.xmlformat.xml: -------------------------------------------------------------------------------- 1 | 2 | 5 | %entities; 6 | ]> 7 | 8 | Formatting XML 9 | 10 | This section provides information on formatting XML sources. 11 | 12 | 13 | 14 | 15 | Line ends: 16 | 17 | Lines should end with a Unix line end character (also called line 18 | feed, LF, newline, or \n). 19 | 20 | 21 | 22 | 23 | 24 | Line length: 25 | 26 | Lines should be at most 100 characters long, unless one of the 27 | following exceptions applies: 28 | 29 | 30 | 31 | 32 | 33 | Some computer output, computer input or URIs may run longer and 34 | cannot be broken. 35 | 36 | 37 | 38 | 39 | Some elements become much harder to read if broken. For example, 40 | that can be the case for long 41 | menuchoice elements. 42 | 43 | 44 | 45 | 46 | Aim to minimize the size of diffs in version control, to make 47 | reading diffs more efficient and version control storage more 48 | efficient. For example, if a typo fix introduces a line with 82 49 | characters, consider keeping the line at that length. Also, avoid 50 | reflowing entire paragraphs of text, as that will also lead to 51 | hard-to-read diffs. 52 | 53 | 54 | 55 | 56 | 57 | 58 | Indentation: 59 | 60 | Indent using two space characters per indentation level. Make sure 61 | your editor does not replace spaces with tabs. Documents should not 62 | contain any tab characters. 63 | 64 | 65 | 66 | 67 | 68 | Trailing whitespace: 69 | 70 | Avoid introducing trailing whitespace characters such as spaces, 71 | protected spaces or tabs. Many editors have an option to view such 72 | characters. git diff will show newly introduced 73 | trailing whitespace characters in red. 74 | 75 | 76 | 77 | 78 | 79 | Formatting of block elements: 80 | 81 | Block elements are all DocBook elements that create a rectangular 82 | visual block in the layout, such as para, 83 | table or 84 | figure. Format block elements with new 85 | lines before and after each tag and make sure they follow the 86 | indentation of the document: 87 | 88 | 89 | 90 | <block> 91 | Content of block, indented by a space. 92 | </block> 93 | 94 | 95 | For information about the usage of screen, 96 | see . 97 | 98 | 99 | 100 | 101 | Formatting of inline elements: 102 | 103 | Block elements are all DocBook elements that can be reflowed freely 104 | within a block element, such as emphasis, 105 | keycap, or 106 | guimenu. Format inline elements along 107 | with other inline content without adding newlines or extra 108 | indentation: 109 | 110 | 111 | 112 | <block> 113 | Content of block <inline>content of inline</inline>. 114 | <block> 115 | 116 | 117 | 118 | 119 | Formatting of title elements: 120 | 121 | The title elements title and 122 | term are block elements. However, they 123 | provoke a style sheet quirk and should be treated differently. This 124 | avoids superfluous whitespace when used in the context of a 125 | cross-reference. Format title elements with new lines before the 126 | opening tag and after the closing tag and make sure they follow the 127 | indentation of the document: 128 | 129 | 130 | 131 | <title>Content of Title</block> 132 | 133 | 134 | 135 | 136 | Formatting of computer output/computer input blocks: 137 | 138 | The Computer Output/Computer Input Block Element 139 | screen should be treated like a block 140 | element but multi-line screen elements 141 | should not be indented to aid source reading flow and avoid the trap 142 | of adding extraneous leading space to their content. (Single-line 143 | screen can be indented). 144 | 145 | 146 | 147 | 148 | 149 | XML comments 150 | 151 | XML comments should follow the indentation of the document. Where 152 | feasible, put XML comments on new lines to make reading diffs and 153 | later removal of the comment easier: 154 | 155 | 156 | 157 | <block> 158 | Block content. 159 | <!-- An XML comment --> 160 | </block> 161 | 162 | 163 | XML comments must not contain the characters --. To 164 | preserve such character combinations within comments, replace them with 165 | -/-. 166 | 167 | 168 | For information about the usage of XML comments, see 169 | . 170 | 171 | 172 | 173 | 174 | Reflowing entire files: 175 | 176 | Before reflowing entire files to a different XML formatting style, 177 | weigh the cost of keeping the document in its current state against 178 | the cost of reflowing. Reflowing often makes it easier to work with 179 | the document. However, if the document has a rich editing history 180 | already, reflowing makes it harder to properly use tools like 181 | git blame. 182 | 183 | 184 | 185 | 186 | 187 | To easily convert documents to this style after importing them, use the 188 | commands daps xmlformat (for an entire document) and 189 | daps-xmlformat (for a single file). Note that while 190 | these tools are very good otherwise, they do not reflow XML comments 191 | properly. 192 | 193 | 194 | -------------------------------------------------------------------------------- /xml/gfdl.xml: -------------------------------------------------------------------------------- 1 | 2 | 5 | %entities; 6 | ]> 7 | 8 | GNU Free Documentation License 9 | 10 | 11 | Version 1.2, November 2002 12 | 13 | 14 | Copyright (C) 2000,2001,2002 Free Software Foundation, Inc. 59 Temple 15 | Place, Suite 330, Boston, MA 02111-1307 USA 16 | 17 | 18 | Everyone is permitted to copy and distribute verbatim copies of this 19 | license document, but changing it is not allowed. 20 | 21 | 22 | PREAMBLE 23 | 24 | 25 | The purpose of this License is to make a manual, textbook, or other 26 | functional and useful document “free” in the sense of 27 | freedom: to assure everyone the effective freedom to copy and 28 | redistribute it, with or without modifying it, either commercially or 29 | noncommercially. Secondarily, this License preserves for the author and 30 | publisher a way to get credit for their work, while not being considered 31 | responsible for modifications made by others. 32 | 33 | 34 | 35 | This License is a kind of copyleft, which means that 36 | derivative works of the document must themselves be free in the same 37 | sense. It complements the GNU General Public License, which is a copyleft 38 | license designed for free software. 39 | 40 | 41 | 42 | We have designed this License in order to use it for manuals for free 43 | software, because free software needs free documentation: a free program 44 | should come with manuals providing the same freedoms that the software 45 | does. But this License is not limited to software manuals; it can be used 46 | for any textual work, regardless of subject matter or whether it is 47 | published as a printed book. We recommend this License principally for 48 | works whose purpose is instruction or reference. 49 | 50 | 51 | 52 | APPLICABILITY AND DEFINITIONS 53 | 54 | 55 | This License applies to any manual or other work, in any medium, that 56 | contains a notice placed by the copyright holder saying it can be 57 | distributed under the terms of this License. Such a notice grants a 58 | world-wide, royalty-free license, unlimited in duration, to use that work 59 | under the conditions stated herein. The Document, below, 60 | refers to any such manual or work. Any member of the public is a 61 | licensee, and is addressed as you. You accept the license 62 | if you copy, modify or distribute the work in a way requiring permission 63 | under copyright law. 64 | 65 | 66 | 67 | A Modified Version of the Document means any work 68 | containing the Document or a portion of it, either copied verbatim, or 69 | with modifications and/or translated into another language. 70 | 71 | 72 | 73 | A Secondary Section is a named appendix or a front-matter 74 | section of the Document that deals exclusively with the relationship of 75 | the publishers or authors of the Document to the Document’s overall 76 | subject (or to related matters) and contains nothing that could fall 77 | directly within that overall subject. (Thus, if the Document is in part a 78 | textbook of mathematics, a Secondary Section may not explain any 79 | mathematics.) The relationship could be a matter of historical connection 80 | with the subject or with related matters, or of legal, commercial, 81 | philosophical, ethical or political position regarding them. 82 | 83 | 84 | 85 | The Invariant Sections are certain Secondary Sections 86 | whose titles are designated, as being those of Invariant Sections, in the 87 | notice that says that the Document is released under this License. If a 88 | section does not fit the above definition of Secondary then it is not 89 | allowed to be designated as Invariant. The Document may contain zero 90 | Invariant Sections. If the Document does not identify any Invariant 91 | Sections then there are none. 92 | 93 | 94 | 95 | The Cover Texts are certain short passages of text that 96 | are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that 97 | says that the Document is released under this License. A Front-Cover Text 98 | may be at most 5 words, and a Back-Cover Text may be at most 25 words. 99 | 100 | 101 | 102 | A Transparent copy of the Document means a 103 | machine-readable copy, represented in a format whose specification is 104 | available to the general public, that is suitable for revising the 105 | document straightforwardly with generic text editors or (for images 106 | composed of pixels) generic paint programs or (for drawings) some widely 107 | available drawing editor, and that is suitable for input to text 108 | formatters or for automatic translation to a variety of formats suitable 109 | for input to text formatters. A copy made in an otherwise Transparent 110 | file format whose markup, or absence of markup, has been arranged to 111 | thwart or discourage subsequent modification by readers is not 112 | Transparent. An image format is not Transparent if used for any 113 | substantial amount of text. A copy that is not Transparent 114 | is called Opaque. 115 | 116 | 117 | 118 | Examples of suitable formats for Transparent copies include plain ASCII 119 | without markup, Texinfo input format, LaTeX input format, SGML or XML 120 | using a publicly available DTD, and standard-conforming simple HTML, 121 | PostScript or PDF designed for human modification. Examples of 122 | transparent image formats include PNG, XCF and JPG. Opaque formats 123 | include proprietary formats that can be read and edited only by 124 | proprietary word processors, SGML or XML for which the DTD and/or 125 | processing tools are not generally available, and the machine-generated 126 | HTML, PostScript or PDF produced by some word processors for output 127 | purposes only. 128 | 129 | 130 | 131 | The Title Page means, for a printed book, the title page 132 | itself, plus such following pages as are needed to hold, legibly, the 133 | material this License requires to appear in the title page. For works in 134 | formats which do not have any title page as such, Title 135 | Page means the text near the most prominent appearance of the 136 | work’s title, preceding the beginning of the body of the text. 137 | 138 | 139 | 140 | A section Entitled XYZ means a named subunit of the 141 | Document whose title either is precisely XYZ or contains XYZ in 142 | parentheses following text that translates XYZ in another language. (Here 143 | XYZ stands for a specific section name mentioned below, such as 144 | Acknowledgements, Dedications, 145 | Endorsements, or History.) To 146 | Preserve the Title of such a section when you modify the 147 | Document means that it remains a section Entitled XYZ 148 | according to this definition. 149 | 150 | 151 | 152 | The Document may include Warranty Disclaimers next to the notice which 153 | states that this License applies to the Document. These Warranty 154 | Disclaimers are considered to be included by reference in this License, 155 | but only as regards disclaiming warranties: any other implication that 156 | these Warranty Disclaimers may have is void and has no effect on the 157 | meaning of this License. 158 | 159 | 160 | 161 | VERBATIM COPYING 162 | 163 | 164 | You may copy and distribute the Document in any medium, either 165 | commercially or noncommercially, provided that this License, the 166 | copyright notices, and the license notice saying this License applies to 167 | the Document are reproduced in all copies, and that you add no other 168 | conditions whatsoever to those of this License. You may not use technical 169 | measures to obstruct or control the reading or further copying of the 170 | copies you make or distribute. However, you may accept compensation in 171 | exchange for copies. If you distribute a large enough number of copies 172 | you must also follow the conditions in section 3. 173 | 174 | 175 | 176 | You may also lend copies, under the same conditions stated above, and you 177 | may publicly display copies. 178 | 179 | 180 | 181 | COPYING IN QUANTITY 182 | 183 | 184 | If you publish printed copies (or copies in media that commonly have 185 | printed covers) of the Document, numbering more than 100, and the 186 | Document’s license notice requires Cover Texts, you must enclose 187 | the copies in covers that carry, clearly and legibly, all these Cover 188 | Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the 189 | back cover. Both covers must also clearly and legibly identify you as the 190 | publisher of these copies. The front cover must present the full title 191 | with all words of the title equally prominent and visible. You may add 192 | other material on the covers in addition. Copying with changes limited to 193 | the covers, as long as they preserve the title of the Document and 194 | satisfy these conditions, can be treated as verbatim copying in other 195 | respects. 196 | 197 | 198 | 199 | If the required texts for either cover are too voluminous to fit legibly, 200 | you should put the first ones listed (as many as fit reasonably) on the 201 | actual cover, and continue the rest onto adjacent pages. 202 | 203 | 204 | 205 | If you publish or distribute Opaque copies of the Document numbering more 206 | than 100, you must either include a machine-readable Transparent copy 207 | along with each Opaque copy, or state in or with each Opaque copy a 208 | computer-network location from which the general network-using public has 209 | access to download using public-standard network protocols a complete 210 | Transparent copy of the Document, free of added material. If you use the 211 | latter option, you must take reasonably prudent steps, when you begin 212 | distribution of Opaque copies in quantity, to ensure that this 213 | Transparent copy will remain thus accessible at the stated location until 214 | at least one year after the last time you distribute an Opaque copy 215 | (directly or through your agents or retailers) of that edition to the 216 | public. 217 | 218 | 219 | 220 | It is requested, but not required, that you contact the authors of the 221 | Document well before redistributing any large number of copies, to give 222 | them a chance to provide you with an updated version of the Document. 223 | 224 | 225 | 226 | MODIFICATIONS 227 | 228 | 229 | You may copy and distribute a Modified Version of the Document under the 230 | conditions of sections 2 and 3 above, provided that you release the 231 | Modified Version under precisely this License, with the Modified Version 232 | filling the role of the Document, thus licensing distribution and 233 | modification of the Modified Version to whoever possesses a copy of it. 234 | In addition, you must do these things in the Modified Version: 235 | 236 | 237 | 238 | A. 239 | 240 | Use in the Title Page (and on the covers, if any) a title distinct from 241 | that of the Document, and from those of previous versions (which 242 | should, if there were any, be listed in the History section of the 243 | Document). You may use the same title as a previous version if the 244 | original publisher of that version gives permission. 245 | 246 | 247 | 248 | 249 | B. 250 | 251 | List on the Title Page, as authors, one or more persons or entities 252 | responsible for authorship of the modifications in the Modified 253 | Version, together with at least five of the principal authors of the 254 | Document (all of its principal authors, if it has fewer than five), 255 | unless they release you from this requirement. 256 | 257 | 258 | 259 | 260 | C. 261 | 262 | State on the Title page the name of the publisher of the Modified 263 | Version, as the publisher. 264 | 265 | 266 | 267 | 268 | D. 269 | 270 | Preserve all the copyright notices of the Document. 271 | 272 | 273 | 274 | 275 | E. 276 | 277 | Add an appropriate copyright notice for your modifications adjacent to 278 | the other copyright notices. 279 | 280 | 281 | 282 | 283 | F. 284 | 285 | Include, immediately after the copyright notices, a license notice 286 | giving the public permission to use the Modified Version under the 287 | terms of this License, in the form shown in the Addendum below. 288 | 289 | 290 | 291 | 292 | G. 293 | 294 | Preserve in that license notice the full lists of Invariant Sections 295 | and required Cover Texts given in the Document’s license notice. 296 | 297 | 298 | 299 | 300 | H. 301 | 302 | Include an unaltered copy of this License. 303 | 304 | 305 | 306 | 307 | I. 308 | 309 | Preserve the section Entitled History, Preserve its 310 | Title, and add to it an item stating at least the title, year, new 311 | authors, and publisher of the Modified Version as given on the Title 312 | Page. If there is no section Entitled History in the 313 | Document, create one stating the title, year, authors, and publisher of 314 | the Document as given on its Title Page, then add an item describing 315 | the Modified Version as stated in the previous sentence. 316 | 317 | 318 | 319 | 320 | J. 321 | 322 | Preserve the network location, if any, given in the Document for public 323 | access to a Transparent copy of the Document, and likewise the network 324 | locations given in the Document for previous versions it was based on. 325 | These may be placed in the History section. You may omit 326 | a network location for a work that was published at least four years 327 | before the Document itself, or if the original publisher of the version 328 | it refers to gives permission. 329 | 330 | 331 | 332 | 333 | K. 334 | 335 | For any section Entitled Acknowledgements or 336 | Dedications, Preserve the Title of the section, and 337 | preserve in the section all the substance and tone of each of the 338 | contributor acknowledgements and/or dedications given therein. 339 | 340 | 341 | 342 | 343 | L. 344 | 345 | Preserve all the Invariant Sections of the Document, unaltered in their 346 | text and in their titles. Section numbers or the equivalent are not 347 | considered part of the section titles. 348 | 349 | 350 | 351 | 352 | M. 353 | 354 | Delete any section Entitled Endorsements. Such a section 355 | may not be included in the Modified Version. 356 | 357 | 358 | 359 | 360 | N. 361 | 362 | Do not retitle any existing section to be Entitled 363 | Endorsements or to conflict in title with any Invariant 364 | Section. 365 | 366 | 367 | 368 | 369 | O. 370 | 371 | Preserve any Warranty Disclaimers. 372 | 373 | 374 | 375 | 376 | If the Modified Version includes new front-matter sections or appendices 377 | that qualify as Secondary Sections and contain no material copied from 378 | the Document, you may at your option designate some or all of these 379 | sections as invariant. To do this, add their titles to the list of 380 | Invariant Sections in the Modified Version’s license notice. These 381 | titles must be distinct from any other section titles. 382 | 383 | 384 | 385 | You may add a section Entitled Endorsements, provided it 386 | contains nothing but endorsements of your Modified Version by various 387 | parties--for example, statements of peer review or that the text has been 388 | approved by an organization as the authoritative definition of a 389 | standard. 390 | 391 | 392 | 393 | You may add a passage of up to five words as a Front-Cover Text, and a 394 | passage of up to 25 words as a Back-Cover Text, to the end of the list of 395 | Cover Texts in the Modified Version. Only one passage of Front-Cover Text 396 | and one of Back-Cover Text may be added by (or through arrangements made 397 | by) any one entity. If the Document already includes a cover text for the 398 | same cover, previously added by you or by arrangement made by the same 399 | entity you are acting on behalf of, you may not add another; but you may 400 | replace the old one, on explicit permission from the previous publisher 401 | that added the old one. 402 | 403 | 404 | 405 | The author(s) and publisher(s) of the Document do not by this License 406 | give permission to use their names for publicity for or to assert or 407 | imply endorsement of any Modified Version. 408 | 409 | 410 | 411 | COMBINING DOCUMENTS 412 | 413 | 414 | You may combine the Document with other documents released under this 415 | License, under the terms defined in section 4 above for modified 416 | versions, provided that you include in the combination all of the 417 | Invariant Sections of all of the original documents, unmodified, and list 418 | them all as Invariant Sections of your combined work in its license 419 | notice, and that you preserve all their Warranty Disclaimers. 420 | 421 | 422 | 423 | The combined work need only contain one copy of this License, and 424 | multiple identical Invariant Sections may be replaced with a single copy. 425 | If there are multiple Invariant Sections with the same name but different 426 | contents, make the title of each such section unique by adding at the end 427 | of it, in parentheses, the name of the original author or publisher of 428 | that section if known, or else a unique number. Make the same adjustment 429 | to the section titles in the list of Invariant Sections in the license 430 | notice of the combined work. 431 | 432 | 433 | 434 | In the combination, you must combine any sections Entitled 435 | History in the various original documents, forming one 436 | section Entitled History; likewise combine any sections 437 | Entitled Acknowledgements, and any sections Entitled 438 | Dedications. You must delete all sections Entitled 439 | Endorsements. 440 | 441 | 442 | 443 | COLLECTIONS OF DOCUMENTS 444 | 445 | 446 | You may make a collection consisting of the Document and other documents 447 | released under this License, and replace the individual copies of this 448 | License in the various documents with a single copy that is included in 449 | the collection, provided that you follow the rules of this License for 450 | verbatim copying of each of the documents in all other respects. 451 | 452 | 453 | 454 | You may extract a single document from such a collection, and distribute 455 | it individually under this License, provided you insert a copy of this 456 | License into the extracted document, and follow this License in all other 457 | respects regarding verbatim copying of that document. 458 | 459 | 460 | 461 | AGGREGATION WITH INDEPENDENT WORKS 462 | 463 | 464 | A compilation of the Document or its derivatives with other separate and 465 | independent documents or works, in or on a volume of a storage or 466 | distribution medium, is called an “aggregate” if the 467 | copyright resulting from the compilation is not used to limit the legal 468 | rights of the compilation’s users beyond what the individual works 469 | permit. When the Document is included in an aggregate, this License does 470 | not apply to the other works in the aggregate which are not themselves 471 | derivative works of the Document. 472 | 473 | 474 | 475 | If the Cover Text requirement of section 3 is applicable to these copies 476 | of the Document, then if the Document is less than one half of the entire 477 | aggregate, the Document’s Cover Texts may be placed on covers that 478 | bracket the Document within the aggregate, or the electronic equivalent 479 | of covers if the Document is in electronic form. Otherwise they must 480 | appear on printed covers that bracket the whole aggregate. 481 | 482 | 483 | 484 | TRANSLATION 485 | 486 | 487 | Translation is considered a kind of modification, so you may distribute 488 | translations of the Document under the terms of section 4. Replacing 489 | Invariant Sections with translations requires special permission from 490 | their copyright holders, but you may include translations of some or all 491 | Invariant Sections in addition to the original versions of these 492 | Invariant Sections. You may include a translation of this License, and 493 | all the license notices in the Document, and any Warranty Disclaimers, 494 | provided that you also include the original English version of this 495 | License and the original versions of those notices and disclaimers. In 496 | case of a disagreement between the translation and the original version 497 | of this License or a notice or disclaimer, the original version will 498 | prevail. 499 | 500 | 501 | 502 | If a section in the Document is Entitled Acknowledgements, 503 | Dedications, or History, the requirement 504 | (section 4) to Preserve its Title (section 1) will typically require 505 | changing the actual title. 506 | 507 | 508 | 509 | TERMINATION 510 | 511 | 512 | You may not copy, modify, sublicense, or distribute the Document except 513 | as expressly provided for under this License. Any other attempt to copy, 514 | modify, sublicense or distribute the Document is void, and will 515 | automatically terminate your rights under this License. However, parties 516 | who have received copies, or rights, from you under this License will not 517 | have their licenses terminated so long as such parties remain in full 518 | compliance. 519 | 520 | 521 | 522 | FUTURE REVISIONS OF THIS LICENSE 523 | 524 | 525 | The Free Software Foundation may publish new, revised versions of the GNU 526 | Free Documentation License from time to time. Such new versions will be 527 | similar in spirit to the present version, but may differ in detail to 528 | address new problems or concerns. See 529 | http://www.gnu.org/copyleft/. 530 | 531 | 532 | 533 | Each version of the License is given a distinguishing version number. If 534 | the Document specifies that a particular numbered version of this License 535 | or any later version applies to it, you have the option of 536 | following the terms and conditions either of that specified version or of 537 | any later version that has been published (not as a draft) by the Free 538 | Software Foundation. If the Document does not specify a version number of 539 | this License, you may choose any version ever published (not as a draft) 540 | by the Free Software Foundation. 541 | 542 | 543 | 544 | ADDENDUM: How to use this License for your documents 545 | 546 | 547 | To use this License in a document you have written, include a copy of the 548 | License in the document and put the following copyright and license 549 | notices just after the title page: 550 | 551 | 552 | 553 | Copyright (c) YEAR YOUR NAME. 554 | Permission is granted to copy, distribute and/or modify this document 555 | under the terms of the GNU Free Documentation License, Version 1.2 556 | or any later version published by the Free Software Foundation; 557 | with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. 558 | A copy of the license is included in the section entitled “GNU 559 | Free Documentation License”. 560 | 561 | 562 | 563 | If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, 564 | replace the “with...Texts.” line with this: 565 | 566 | 567 | 568 | with the Invariant Sections being LIST THEIR TITLES, with the 569 | Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. 570 | 571 | 572 | 573 | If you have Invariant Sections without Cover Texts, or some other 574 | combination of the three, merge those two alternatives to suit the 575 | situation. 576 | 577 | 578 | 579 | If your document contains nontrivial examples of program code, we 580 | recommend releasing these examples in parallel under your choice of free 581 | software license, such as the GNU General Public License, to permit their 582 | use in free software. 583 | 584 | 585 | 586 | -------------------------------------------------------------------------------- /xml/legal_suse+gfdl.xml: -------------------------------------------------------------------------------- 1 | 2 | 5 | %entities; 6 | ]> 7 | 8 | 9 | Copyright © 2007– 10 | 11 | SUSE LLC and contributors. All rights reserved. 12 | 13 | 14 | Permission is granted to copy, distribute and/or modify this document under 15 | the terms of the GNU Free Documentation License, Version 1.2 or (at your 16 | option) version 1.3; with the Invariant Section being this copyright notice 17 | and license. A copy of the license version 1.2 is included in the section 18 | entitled GNU Free Documentation License. 19 | 20 | 21 | For &suse; trademarks, see 22 | . All other 23 | third-party trademarks are the property of their respective owners. 24 | Trademark symbols (®, ™ etc.) denote trademarks of &suse; and its 25 | affiliates. Asterisks (*) denote third-party trademarks. 26 | 27 | 28 | All information found in this book has been compiled with utmost attention 29 | to detail. However, this does not guarantee complete accuracy. Neither SUSE 30 | LLC, its affiliates, the authors nor the translators shall be held liable 31 | for possible errors or the consequences thereof. 32 | 33 | 34 | -------------------------------------------------------------------------------- /xml/network-entities.ent: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39 | 40 | 41 | 42 | 43 | 44 | 45 | 46 | 47 | 48 | 49 | 50 | 51 | 52 | 53 | 54 | 55 | 56 | 57 | 58 | 59 | 60 | 61 | 62 | 63 | 64 | 65 | 66 | 67 | 68 | 69 | 70 | 71 | 72 | 73 | 74 | 75 | 76 | 77 | 78 | 79 | 80 | 81 | 82 | 83 | 84 | 85 | 86 | 87 | 88 | 89 | 90 | 91 | 92 | 93 | 94 | 95 | 96 | 97 | 98 | 99 | 100 | 101 | 102 | 103 | 104 | 105 | 106 | 107 | 108 | 109 | 110 | 111 | 112 | 113 | 114 | 115 | 116 | 117 | 118 | 119 | 120 | 121 | 122 | 123 | 124 | 125 | 126 | 127 | 128 | 129 | 130 | 131 | 132 | 133 | 134 | 135 | 136 | 137 | 138 | 139 | 140 | 141 | 142 | 143 | 144 | 145 | 146 | 147 | 148 | 149 | 150 | 151 | 152 | 153 | 154 | 155 | 156 | 157 | 158 | 159 | 160 | 161 | 162 | 163 | 164 | 165 | 166 | 167 | 168 | 169 | 170 | 171 | 172 | 173 | 174 | 175 | 176 | 177 | 178 | 179 | 180 | 181 | -------------------------------------------------------------------------------- /xml/product-entities.ent: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | &suse; Documentation Style Guide (DocBookAsciiDoc)"> 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | --------------------------------------------------------------------------------