From b63e1b1ffdfa92d21afa525ddc8bd90bb67a9f46 Mon Sep 17 00:00:00 2001 From: Daria Vladykina Date: Wed, 24 Jul 2024 12:32:58 +0300 Subject: [PATCH] Make 2024-07 release --- xml/docu_styleguide.asciidoc.xml | 89 +- xml/docu_styleguide.changes.xml | 2661 ++++++------ xml/docu_styleguide.content.xml | 57 +- xml/docu_styleguide.contributors.xml | 13 +- xml/docu_styleguide.language.xml | 52 +- xml/docu_styleguide.manage.xml | 631 +-- xml/docu_styleguide.name.xml | 115 +- xml/docu_styleguide.outline.xml | 497 +-- xml/docu_styleguide.smartdocs.xml | 590 +-- xml/docu_styleguide.structure.xml | 5675 +++++++++++++------------- xml/docu_styleguide.taglist.xml | 1791 ++++---- xml/docu_styleguide.techwriting.xml | 137 +- xml/docu_styleguide.terminology.xml | 4035 +++++++++--------- xml/docu_styleguide.webwriting.xml | 419 +- xml/docu_styleguide.xmlformat.xml | 317 +- xml/entity-decl.ent | 2 +- xml/gfdl.xml | 1120 ++--- xml/legal_suse+gfdl.xml | 50 +- 18 files changed, 9346 insertions(+), 8905 deletions(-) diff --git a/xml/docu_styleguide.asciidoc.xml b/xml/docu_styleguide.asciidoc.xml index 34193604..cd4f1bef 100644 --- a/xml/docu_styleguide.asciidoc.xml +++ b/xml/docu_styleguide.asciidoc.xml @@ -5,51 +5,54 @@ %entities; ]> - Working with AsciiDoc - - To create documentation in the AsciiDoc format, - adhere to the comprehensive guide at . - - We also recommend the guidance on AsciiDoc provided in the - SUSE Technical Reference Documentation Contributors Guide. - - The following things are important when working with AsciiDoc: - - - - - Only use formatting that is supported by the AsciiDoctor tool. - Ignore features that are only documented for the outdated - asciidoc (Python) tool. In particular, ignore the - documentation at https://powerman.name. - - - - - - Most recommendations from - - are applicable generally. Some recommendations, however, are specific to - &suse; Manager documentation, in particular: - - + Working with AsciiDoc + + To create documentation in the AsciiDoc format, adhere to the comprehensive + guide at + . + + + We also recommend the guidance on AsciiDoc provided in the + SUSE + Technical Reference Documentation Contributors Guide. + + + The following things are important when working with AsciiDoc: + + - - The section Images—images need to be added - the same way they are added in other DAPS-based documentation, under the - images/src/FORMAT - directory of the repo. - + + Only use formatting that is supported by the AsciiDoctor tool. Ignore + features that are only documented for the outdated + asciidoc (Python) tool. In particular, ignore the + documentation at https://powerman.name. + + - - The section Working with Drafts—there is - currently no equivalent standard functionality. - + + Most recommendations from + + are applicable generally. Some recommendations, however, are specific + to &suse; Manager documentation, in particular: + + + + + The section Images—images need to be + added the same way they are added in other DAPS-based + documentation, under the + images/src/FORMAT + directory of the repo. + + + + + The section Working with Drafts—there + is currently no equivalent standard functionality. + + + - - - - - + diff --git a/xml/docu_styleguide.changes.xml b/xml/docu_styleguide.changes.xml index 7fc06132..7a64412c 100644 --- a/xml/docu_styleguide.changes.xml +++ b/xml/docu_styleguide.changes.xml @@ -7,1152 +7,1521 @@ - - - - - - 2024-05 - - - - Updated the Entities subsection in - Managing documents: common types of entities and their - use cases, the Doc Kit repository that maintains official generic entities, - creating custom entities, and entity files. - - - Updated the Prompts subsection in Structure - and markup with clearer info on using prompts and prompt entities - (always specify regular or elevated privileges). - - - Terminology update: flash disk → flash drive, in sync with TermWeb. - - - Language and Terminology updated with - info about TermWeb that is now fully launched and available to all SUSE employees. - - - The style guide changed its structure to the three-column layout with clearly - featured subsections. - - - - - - - 2024-02 - - - - Added a new section on Profiling to the Structure - and markup chapter. - - - Updated the introduction to Structure and markup - with links to doc-kit that now hosts examples of rendered books - and articles. - - - More in Structure and markup: links to - READMEs in doc-modular to find naming conventions for file - and figure names, and guidelines for using the - xrefstyle attribute—only use the tags - select: and template: - with it to customize cross-links. - - - Added clarified reference on using entities to create generic names - in the Names of example items chapter, with the link to - doc-kit. - - - - - - - 2023-11 - - - - Created a new Revision history that opens as a - separate file and is linked from the main doc. Added info about - this in the Smart Docs chapter: Use the - revhistory tag in the - info part of XML file. - - - Updated the rules for creating glossaries in section Glossaries, - which also contains an example of the specific structure that must - be used. A style sheet update now supports the automatic alphabetical - ordering of items. - - - Updated the Structure and markup chapter: Use the - href element to provide cross-references - only within the same doc set; the tag citetitle - is not translated and must only reference names of printed books (section - DocBook tags, Inline elements). - - - - - - - 2023-09 - - - - Updated the chapter on AsciiDoc: sorted the recommendations and - added the link to the guidance on AsciiDoc in Technical Reference - Documentation. - - - Updated the Language chapter with info on product names. If a - product name is not in the style guide's Terminology table or in the - entities Doc Kit file, refer to the official SUSE Products page and the - Marketing department. Do not use articles in front of product names. - - - - New items in the Terminology table: since rejected in - the meaning of because; timeout and - system-wide added as approved terms. Data - only requires singular, so data is is approved and - data are is rejected. - - - - - - - 2023-06 - - - - Added a new chapter on Smart Docs, describing the principle, the - structure and its building blocks. - - - Updated the recommended minimal title length with 29 characters for - SEO purposes. - - - Updated the Inline elements table in the - DocBook Tags chapter: added the guidance to use the secure - protocol prefix https:// and to use the package tag to replace systemitem - class="resource". - - - Added information on the use of the formalpara tag. - - - Added information about the element phrase role="style:sentencecase" - for the style sheets to expand the relevant entities as uppercase, when - needed. - - - Updated the Terminology table with drop-down list, - list box and right-, left-, middle click. - - - - - - - - 2023-02 - - - - Finalized the file and image naming conventions and provided a - reference to the doc-modular repository in the Structure and - Markup chapter. - - - Added rules for quotation marks in chapter - Language only use them in quotes; in other cases, use - the emphasis element to make words or phrases more - conspicuous. - - - Added the guidance to avoid using single quotation marks. - - - Updated the Structure and Markup chapter with the - instruction to not use articles before book and chapter titles when - referencing them. - - - Updated rules for the line length (100 char now) and indentation - (2-space characters now) in section Formatting XML. - - - - Clarified the usage of the term register to/with in - Terminology. - - - - - - - - 2022-11 - - - - Added new content, updated and restructured the content of the - Cross-references section (a warning not to include xref - elements into titles). - - - Updated the Screens subsection with the info on - automatic syntax highlighting. - - - Expanded the rule of using the comma - no use of comma in simple - series like x, y and z. - - - Described how you can group different callouts to point to the same - annotation in the text (helps avoid repeating the same annotation). - - - - Updated chapter Language with punctuation rules for - quotation marks - commas and periods go inside them per AE punctuation - rules. - - - Added terms: unit, - unit file, - console, - shell, - terminal, - init script, and whitespace. - - - - - - - - 2022-08 - - - - Added new content on the correct use of doc.suse.com URL in the - ‘External links to SUSE documentation’ subsection - - - Added general instructions on how to create and style tables in the - section ‘Structure and markup’ - - - Added a subsection about hyphens to the ‘Language’ section - - - Added and updated terms and definitions: ‘bare metal’, ‘drop-down - list’, ‘list box’, ‘screen’, ‘usage’, ‘utilization’, ‘view’, - ‘multi-version’ (adjective) - - - - - - - 2022-06 - - - - Added a section on localization-friendly writing in the 'Web - writing' chapter - - - Added a section on creating SP-independent links to the chapter - ‘Structure and markup’ - - - Added definitions of program, application, script, command, tool, - form, dialog - - - Updated the 'DocBook tags' section of the style guide (fixed typos - and layout) - - - Added specification on the use of the % sign - - - Added admonition about version numbers in chapter titles - - - Rearranged sections in "Structure and markup chapter" in - alphabetical order - - - Added terms 'codestream', 'crash dump' - - - Updated guidance on punctuation to use at the end of list items - - - - - - - - 2022-04 - - - - Updated the Abstract instances in Style guide - - - Updated the chapter abstract wording and the example of an abstract - to match the char limit. - - - Added a section on Web writing and SEO-friendly content - - - Added a section on Tech writing to replace the Audience section - - - - Added a section about DocBook tags allowlist - - - Added terms: 'changelog', 'real time', 'coldplug' - - - Minor bug fixes of the style guide - - - - - - - 2021-12 - - Updated recommendations for abstracts and - highlights: Always add an abstract to chapters, - with a length of 70 and 150 characters. Do not use highlights. - - - - - 2021-10 - - - - Updated recommended prompt style: Where possible, use short prompts - such as >  or # . - - - Updated the definitions of installation medium - and installation source to clarify that - installation medium should only be used where a - physical medium is concerned. - - - Added rules for when multiple commands can be combined within a - single screen element. - - - - - - - 2021-08 - - - - Updated the spelling of lifecycle (former - spelling, life cycle). - - - Updated recommendations on how to list contributors. Change - Contributors appendix accordingly. - - - Mentioned that placeholders must not contain spaces. - - - - - - - 2021-04 - - - - Updated the standard title for sections comprising of references to - other documents from For more information to - More information. - - - Mentioned Doc Kit default entity file. - - - Added examples for hyphenation and file names/directory names. - - - - Clarified/shortened/reformatted various language advice. Improved - wording consistency of references to other sections of the guide. - - - - - - - 2021-02 - - - - Mentioned that we support the Inclusive Naming Initiative. - - - Added section about rules for linking to external sites. - - - Added a section about avoiding promises of future features. - - - Mentioned that UI labels should always be capitalized as they are - capitalized in the UI. - - - Clarified section about abbreviations. - - - Improved structure of capitalization section. - - - - - - - 2020-12 - - - - Updated the Style Guide to recommend the use of sentence case for - titles. Book, article, and set titles are to remain in title case. - - - Added guideline when to use noun-based and when to use verb-based - headings. - - - - - - - 2020-10 - - - - Explained issues with URL shorteners. - - - Clarified section on creating IDs by removing confusing left-overs - from description of former .-based ID scheme. - - - Clarified and updated section about entities. Entities are not used - during translation. - - - Updated XInclude section. XIncluded documents can also be - plain-text. - - - Updated formatting of XML examples across the document to 1-space - indent, as is encouraged in the XML formatting section of this document. - - - - Removed Indexes section. There has not been a practical use of this - section in several years. - - - Updated advice on lists. Deduplicated the sections about lists in - the Structure and Markup section versus the section - in the Language section. Aligned list terminology - with DocBook terminology. - - - Improved phrasing and fixed minor language and technical errors - across the document. - - - - - - - 2020-08 - - - - Removed outdated and overly specific recommendation to use Shutter - application from section Screenshots. - - - Clarified section Outline. Included better guidance for article - outlines. Clarified when to contact product managers. Removed outdated - reference to SVN metadata. - - - Updated URLs of DocBook Definitive Guide. Updated URLs to HTTPS. - - - - Moved advice to include at least introductory content in each - section from Language/Headings section to Structure/Outlining section. - - - - Clarified that admonition titles should use title style. - - - Removed listing of document authors. - - - Made language fixes, clarifications, and added explanations. - - - - - - - 2019-11 - - Added guidance regarding appropriate on-page screenshot sizing. - - - - - - 2019-08 - - Added minimal guidance regarding AsciiDoc documents. - - - - - 2019-07 - - Updated guidance regarding use of . and - _ in XML IDs. - - - - - 2019-03 - - Added guidance regarding easily outdated information in screens and - screenshots. - - - - - 2018-11 - - - - Added terminology entry for subsystem. - - - Improved guidance regarding numbers and measurments. - - - - - - - 2018-08 - - Improved guidance regarding path names. - - - - - 2018-07 - - - - Added guidance regarding XML formatting. - - - Improved guidance regarding commands. - - - - - - - 2018-06 - - - - Documented ID prefix for prefaces. - - - Added guidance regarding scaling of screenshots. - - - - - - - 2018-04 - - Added terminology entry for namespace. - - - - - 2017-11 - - Improved guidance regarding XML IDs. - - - - - 2017-10 - - Updated terminology entry for IBM Z. - - - - - 2017-04 - - Added terminology entries for e-mail, - hot key. - - - - - 2017-03 - - - - Added terminology entries for use case, - business case. - - - Improved guidance regarding use of prompts. - - - Added guidance regarding list structure. - - - - - - - 2016-12 - - Corrected SLES for SAP Applications product name. - - - - - 2016-07 - - - July 2016 Major Update Version 2016-07 was a major update focused on - adding terminology, fixing errors, and making the guide DocBook - 5-compatible. Version 2014-02.2 was released on 2016-07-01. - - - Migrated style guide from SVN to Git. Migrated style guide from - DocBook 4.3 to DocBook 5.1. Switched to using profiling instead of two - MAIN files for being able to customize contents based - on the DC file. Added Report Bug link. - - - Updated style guide for use with DocBook 5.1 and GeekoDoc. - - - Improved clarity. Fixed typographical and grammar issues. Brought - Style Guide into better compliance with itself using the style checker. - - - - Updated legal notice reproduced in . - - - - Added . - - - Added . Removed some now-duplicated - content out of . - - - Corrected syntax of : textobject must be within mediaobject. - - - Updated terminology and general vocabulary tables in . - - - Added entries for AArch64, - AMD64/Intel 64, cursor, - for instance, IA64, - kernel space, KIWI, - live CD, live DVD, - live image, pointer, - POWER, Samba, SUSE - Enterprise Storage, SUSE Linux Enterprise Server - for SAP Applications, systemd, - System V init, technology - preview, toolchain, user - space, Web cam, - x86, z Systems, words with - -ward (such as afterward or - backward), - - - Changed accepted entry from SUSE Cloud to - SUSE OpenStack Cloud. Updated rejected entries. - - - - Improved definitions of click and - press. - - - Added mask as a rejected entry to - dialog. Added a definition for - dialog. - - - Removed duplicate entry EPUB. - - - Improved alphabetical sorting. - - - - - - - - - 2014-02 - - - Version 2014-02.2 was a minor update focused on adding terminology and - fixing small errors. Version 2014-02.2 was released on 2014-04-24. - - - Improved clarity and fixed typos. - - - Brought Style Guide into better compliance with itself using the - style checker tool. - - - Moved from into . Added - new section with the information on - structure that the former Headings section contained. - - - - Split existing section Abbreviations into and . Added - ,, and - to newly created . - - - Separated list items for id attribute - and title in . - - - Split the table in into and to - better reflect the roles of the terms listed there. - - - Updated terminology and general vocabulary tables in . - - - Added entries for adapter, - architecture, create a hard - link, create a symbolic link, - connect via SSH, init script, - installation medium, log in via - SSH, remove at runtime, - solid-state drive, SSD, - symbolic link, - synchronization, synchronize, - UEFI, Unified Extensible Firmware - Interface, virtualize, - WLAN, with regard to. - - - Changed accepted spellings from Wi-fi to - Wi-Fi, Wi-fi card to - Wi-Fi card, and Wi-fi/Bluetooth - card to Wi-Fi/Bluetooth card. This - matches the correct spelling of the brand. sknorr, 2014-03-19: + + + + 2024-07 + + + + + Added an instruction in the subsection DocBook tags + on when to use the guimenu tag. It is + used to mark up all GUI elements like button, label and menu. + + + + + Updated the instruction in Sentence structure and + increased the word limit for a sentence to 25 words. + + + + + + 2024-05 + + + + + Updated the Entities subsection in Managing + documents: common types of entities and their use cases, + the Doc Kit repository that maintains official generic entities, + creating custom entities, and entity files. + + + + + Updated the Prompts subsection in Structure + and markup with clearer info on using prompts and prompt + entities (always specify regular or elevated privileges). + + + + + Terminology update: flash disk → flash drive, in sync with TermWeb. + + + + + Language and Terminology updated with + info about TermWeb that is now fully launched and available to all + SUSE employees. + + + + + The style guide changed its structure to the three-column layout + with clearly featured subsections. + + + + + + 2024-02 + + + + + Added a new section on Profiling to the Structure and + markup chapter. + + + + + Updated the introduction to Structure and markup + with links to doc-kit that now hosts examples of rendered books and + articles. + + + + + More in Structure and markup: links to READMEs in + doc-modular to find naming conventions for file and figure names, + and guidelines for using the xrefstyle + attribute—only use the tags + select: and + template: with it to customize + cross-links. + + + + + Added clarified reference on using entities to create generic names + in the Names of example items chapter, with the link + to doc-kit. + + + + + + 2023-11 + + + + + Created a new Revision history that opens as a + separate file and is linked from the main doc. Added info about + this in the Smart Docs chapter: Use the + revhistory tag in the + info part of XML file. + + + + + Updated the rules for creating glossaries in section + Glossaries, which also contains an example of the + specific structure that must be used. A style sheet update now + supports the automatic alphabetical ordering of items. + + + + + Updated the Structure and markup chapter: Use the + href element to provide + cross-references only within the same doc set; the tag + citetitle is not translated and must + only reference names of printed books (section DocBook tags, + Inline elements). + + + + + + 2023-09 + + + + + Updated the chapter on AsciiDoc: sorted the recommendations and + added the link to the guidance on AsciiDoc in Technical Reference + Documentation. + + + + + Updated the Language chapter with info on product names. If a + product name is not in the style guide's Terminology table or in + the entities Doc Kit file, refer to the official SUSE Products page + and the Marketing department. Do not use articles in front of + product names. + + + + + New items in the Terminology table: since rejected + in the meaning of because; timeout + and system-wide added as approved terms. + Data only requires singular, so data + is is approved and data are is rejected. + + + + + + 2023-06 + + + + + Added a new chapter on Smart Docs, describing the principle, the + structure and its building blocks. + + + + + Updated the recommended minimal title length with 29 characters for + SEO purposes. + + + + + Updated the Inline elements table in the + DocBook Tags chapter: added the guidance to use the + secure protocol prefix https:// and to use the package tag to + replace systemitem class="resource". + + + + + Added information on the use of the formalpara tag. + + + + + Added information about the element phrase + role="style:sentencecase" for the style sheets to expand the + relevant entities as uppercase, when needed. + + + + + Updated the Terminology table with drop-down list, + list box and right-, left-, middle + click. + + + + + + 2023-02 + + + + + Finalized the file and image naming conventions and provided a + reference to the doc-modular repository in the Structure and + Markup chapter. + + + + + Added rules for quotation marks in chapter + Language only use them in quotes; in other + cases, use the emphasis element to make words + or phrases more conspicuous. + + + + + Added the guidance to avoid using single quotation marks. + + + + + Updated the Structure and Markup chapter with the + instruction to not use articles before book and chapter titles when + referencing them. + + + + + Updated rules for the line length (100 char now) and indentation + (2-space characters now) in section Formatting XML. + + + + + Clarified the usage of the term register to/with in + Terminology. + + + + + + 2022-11 + + + + + Added new content, updated and restructured the content of the + Cross-references section (a warning not to include + xref elements into titles). + + + + + Updated the Screens subsection with the info on + automatic syntax highlighting. + + + + + Expanded the rule of using the comma - no use of comma in simple + series like x, y and z. + + + + + Described how you can group different callouts to point to the same + annotation in the text (helps avoid repeating the same annotation). + + + + + Updated chapter Language with punctuation rules for + quotation marks - commas and periods go inside them per AE + punctuation rules. + + + + + Added terms: unit, unit file, + console, shell, + terminal, init script, and + whitespace. + + + + + + 2022-08 + + + + + Added new content on the correct use of doc.suse.com URL in the + ‘External links to SUSE documentation’ subsection + + + + + Added general instructions on how to create and style tables in the + section ‘Structure and markup’ + + + + + Added a subsection about hyphens to the ‘Language’ section + + + + + Added and updated terms and definitions: ‘bare metal’, ‘drop-down + list’, ‘list box’, ‘screen’, ‘usage’, ‘utilization’, ‘view’, + ‘multi-version’ (adjective) + + + + + + 2022-06 + + + + + Added a section on localization-friendly writing in the 'Web + writing' chapter + + + + + Added a section on creating SP-independent links to the chapter + ‘Structure and markup’ + + + + + Added definitions of program, application, script, command, tool, + form, dialog + + + + + Updated the 'DocBook tags' section of the style guide (fixed typos + and layout) + + + + + Added specification on the use of the % sign + + + + + Added admonition about version numbers in chapter titles + + + + + Rearranged sections in "Structure and markup chapter" in + alphabetical order + + + + + Added terms 'codestream', 'crash dump' + + + + + Updated guidance on punctuation to use at the end of list items + + + + + + 2022-04 + + + + + Updated the Abstract instances in Style guide + + + + + Updated the chapter abstract wording and the example of an abstract + to match the char limit. + + + + + Added a section on Web writing and SEO-friendly content + + + + + Added a section on Tech writing to replace the Audience section + + + + + Added a section about DocBook tags allowlist + + + + + Added terms: 'changelog', 'real time', 'coldplug' + + + + + Minor bug fixes of the style guide + + + + + + 2021-12 + + + Updated recommendations for abstracts and + highlights: Always add an abstract to + chapters, with a length of 70 and 150 characters. Do not use + highlights. + + + + 2021-10 + + + + + Updated recommended prompt style: Where possible, use short prompts + such as >  or + # . + + + + + Updated the definitions of installation medium + and installation source to clarify that + installation medium should only be used where + a physical medium is concerned. + + + + + Added rules for when multiple commands can be combined within a + single screen element. + + + + + + 2021-08 + + + + + Updated the spelling of lifecycle (former + spelling, life cycle). + + + + + Updated recommendations on how to list contributors. Change + Contributors appendix accordingly. + + + + + Mentioned that placeholders must not contain spaces. + + + + + + 2021-04 + + + + + Updated the standard title for sections comprising of references to + other documents from For more information to + More information. + + + + + Mentioned Doc Kit default entity file. + + + + + Added examples for hyphenation and file names/directory names. + + + + + Clarified/shortened/reformatted various language advice. Improved + wording consistency of references to other sections of the guide. + + + + + + 2021-02 + + + + + Mentioned that we support the Inclusive Naming Initiative. + + + + + Added section about rules for linking to external sites. + + + + + Added a section about avoiding promises of future features. + + + + + Mentioned that UI labels should always be capitalized as they are + capitalized in the UI. + + + + + Clarified section about abbreviations. + + + + + Improved structure of capitalization section. + + + + + + 2020-12 + + + + + Updated the Style Guide to recommend the use of sentence case for + titles. Book, article, and set titles are to remain in title case. + + + + + Added guideline when to use noun-based and when to use verb-based + headings. + + + + + + 2020-10 + + + + + Explained issues with URL shorteners. + + + + + Clarified section on creating IDs by removing confusing left-overs + from description of former .-based ID scheme. + + + + + Clarified and updated section about entities. Entities are not used + during translation. + + + + + Updated XInclude section. XIncluded documents can also be + plain-text. + + + + + Updated formatting of XML examples across the document to 1-space + indent, as is encouraged in the XML formatting section of this + document. + + + + + Removed Indexes section. There has not been a practical use of this + section in several years. + + + + + Updated advice on lists. Deduplicated the sections about lists in + the Structure and Markup section versus the + section in the Language section. Aligned + list terminology with DocBook terminology. + + + + + Improved phrasing and fixed minor language and technical errors + across the document. + + + + + + 2020-08 + + + + + Removed outdated and overly specific recommendation to use Shutter + application from section Screenshots. + + + + + Clarified section Outline. Included better guidance for article + outlines. Clarified when to contact product managers. Removed + outdated reference to SVN metadata. + + + + + Updated URLs of DocBook Definitive Guide. Updated URLs to HTTPS. + + + + + Moved advice to include at least introductory content in each + section from Language/Headings section to Structure/Outlining + section. + + + + + Clarified that admonition titles should use title style. + + + + + Removed listing of document authors. + + + + + Made language fixes, clarifications, and added explanations. + + + + + + 2019-11 + + + Added guidance regarding appropriate on-page screenshot sizing. + + + + 2019-08 + + + Added minimal guidance regarding AsciiDoc documents. + + + + 2019-07 + + + Updated guidance regarding use of . and + _ in XML IDs. + + + + 2019-03 + + + Added guidance regarding easily outdated information in screens and + screenshots. + + + + 2018-11 + + + + + Added terminology entry for subsystem. + + + + + Improved guidance regarding numbers and measurments. + + + + + + 2018-08 + + + Improved guidance regarding path names. + + + + 2018-07 + + + + + Added guidance regarding XML formatting. + + + + + Improved guidance regarding commands. + + + + + + 2018-06 + + + + + Documented ID prefix for prefaces. + + + + + Added guidance regarding scaling of screenshots. + + + + + + 2018-04 + + + Added terminology entry for namespace. + + + + 2017-11 + + + Improved guidance regarding XML IDs. + + + + 2017-10 + + + Updated terminology entry for IBM Z. + + + + 2017-04 + + + Added terminology entries for e-mail, + hot key. + + + + 2017-03 + + + + + Added terminology entries for use case, + business case. + + + + + Improved guidance regarding use of prompts. + + + + + Added guidance regarding list structure. + + + + + + 2016-12 + + + Corrected SLES for SAP Applications product name. + + + + 2016-07 + + + July 2016 Major Update Version 2016-07 was a major update focused on + adding terminology, fixing errors, and making the guide DocBook + 5-compatible. Version 2014-02.2 was released on 2016-07-01. + + + + + Migrated style guide from SVN to Git. Migrated style guide from + DocBook 4.3 to DocBook 5.1. Switched to using profiling instead of + two MAIN files for being able to customize + contents based on the DC file. Added Report + Bug link. + + + + + Updated style guide for use with DocBook 5.1 and GeekoDoc. + + + + + Improved clarity. Fixed typographical and grammar issues. Brought + Style Guide into better compliance with itself using the style + checker. + + + + + Updated legal notice reproduced in . + + + + + Added . + + + + + Added . Removed some now-duplicated + content out of . + + + + + Corrected syntax of : + textobject must be within + mediaobject. + + + + + Updated terminology and general vocabulary tables in + . + + + + + Added entries for AArch64, + AMD64/Intel 64, + cursor, for instance, + IA64, kernel space, + KIWI, live CD, + live DVD, live image, + pointer, POWER, + Samba, SUSE Enterprise + Storage, SUSE Linux Enterprise Server for + SAP Applications, systemd, + System V init, technology + preview, toolchain, + user space, Web cam, + x86, z Systems, words + with -ward (such as + afterward or + backward), + + + + + Changed accepted entry from SUSE Cloud to + SUSE OpenStack Cloud. Updated rejected + entries. + + + + + Improved definitions of click and + press. + + + + + Added mask as a rejected entry to + dialog. Added a definition for + dialog. + + + + + Removed duplicate entry EPUB. + + + + + Improved alphabetical sorting. + + + + + + + + 2014-02 + + + Version 2014-02.2 was a minor update focused on adding terminology and + fixing small errors. Version 2014-02.2 was released on 2014-04-24. + + + + + Improved clarity and fixed typos. + + + + + Brought Style Guide into better compliance with itself using the + style checker tool. + + + + + Moved from + into + . Added new section + with the information on + structure that the former Headings section + contained. + + + + + Split existing section Abbreviations into + and + . Added + ,, + and to newly created + . + + + + + Separated list items for id attribute + and title in . + + + + + Split the table in into + and + to better reflect the roles of + the terms listed there. + + + + + Updated terminology and general vocabulary tables in + . + + + + + Added entries for adapter, + architecture, create a hard + link, create a symbolic link, + connect via SSH, init + script, installation medium, + log in via SSH, remove at + runtime, solid-state drive, + SSD, symbolic link, + synchronization, + synchronize, UEFI, + Unified Extensible Firmware Interface, + virtualize, WLAN, + with regard to. + + + + + Changed accepted spellings from Wi-fi to + Wi-Fi, Wi-fi card to + Wi-Fi card, and Wi-fi/Bluetooth + card to Wi-Fi/Bluetooth card. + This matches the correct spelling of the brand. + sknorr, 2014-03-19: Thanks, Tom! - - - - Corrected rejected terms in the entry of AOO. - - - - Added rejected terms to the entries of boot - disk (boot disc), check - box (checking option), flash - disk, hard disk, - hotplug (hotadd, - hotswap), hotpluggable, - hotplugging, press, - slider (slidebar). - - - Removed installation media from rejected terms of - installation source. - - - Improved alphabetical sorting. - - - - - - - - 2014-02 - - - Version 2014-02.1 was a minor update focused on adding terminology and - fixing small errors. Version 2014-02.1 was released on 2014-03-13. - - - Improved clarity and fixed typos. - - - Improved example of a warning in . - - - - Added an instruction where to insert screenshots to . sknorr, 2014-03-05: Thanks, + + + + + Corrected rejected terms in the entry of + AOO. + + + + + Added rejected terms to the entries of boot + disk (boot disc), check + box (checking option), + flash disk, hard + disk, hotplug + (hotadd, hotswap), + hotpluggable, + hotplugging, press, + slider (slidebar). + + + + + Removed installation media from rejected terms + of installation source. + + + + + Improved alphabetical sorting. + + + + + + + + 2014-02 + + + Version 2014-02.1 was a minor update focused on adding terminology and + fixing small errors. Version 2014-02.1 was released on 2014-03-13. + + + + + Improved clarity and fixed typos. + + + + + Improved example of a warning in . + + + + + Added an instruction where to insert screenshots to + . + sknorr, 2014-03-05: Thanks, Frank! - - - - Updated terminology table in . - - - Added entries for AOO, Apache - OpenOffice, Bluetooth, - Bluetooth card, drop-down - box, Ethernet card, HTML - page, HTTPS, KDE, - LibreOffice, Linux, - list box, menu, - OpenOffice.org, OOo, - please, delta RPM, - (to) save sth. (with sub-entries), - selected, terminate, - text box, Wi-fi card, - Wi-fi/Bluetooth card, (to) write - sth. and video DVD. - - - Replaced entry for facilitate with entry for - simplify. - - - Added HTML web page as a rejected entry to - Web page. - - - Added joker as a rejected entry to - wild card. - - - Added screen as a rejected entry to - dialog. - - - Removed graphical UI as a rejected entry from - GUI and graphical user - interface. - - - Clarified usage of (to) close sth., - (to) log in, (to) log out, - and (to) quit sth.. - - - Changed accepted entry from Audio CD to - audio CD. - - - Removed entries for computer and - Kernel. - - - - - - - - - 2014-02 - - - February 2014 Major Update - 2014-02 was a major update focused on restructuring the style guide - and adding terminology. Version 2014-02 was released on 2014-02-18. - - - Restructured large parts of the style guide - - - Removed Creating a Consistent Structure: Lessons for - Lizards section. - - - Renamed Creating a Consistent Structure: Official SUSE - Manuals to Outline of a Manual and - promoted to a sect1. - - - Split the chapter Writing and Editing into - , , and - . Moved the subsections of - Writing and Editing where they fit best. - - - Integrated the Markup appendix into to and . - - - Moved (formerly - Creating Procedures) and (formerly Presenting Computer - Elements) as subsections into . - - - Renamed Discriminatory Language to . - - - Renamed Keys to and promoted it to a sect2 within . - - - Renamed GUI Elements to and promoted it to a sect2 within . - - - - Created and moved , , and as subsections into it. - - - Moved and the copyright notice - into separate DocBook files. - - - - - Restructured terminology list, added more terminology - - - Renamed Spelling Terms to and moved it into an appendix. - - - Centralized much of the information in the introductory paragraph - of Spelling Terms in . - - - Change table layout from two columns (Word or - Phrase and Usage Guideline) to three - (Accepted, Rejected, and Usage - Guideline). - - - Added prefix (to) to all verbs. - - - Added grammatical classification of word to all entries. - - - Added entries for (to) activate sth., - add-on, advice, - (to) advise, after, - although, and, - appendixes, Audio CD, - because of, basically, - (to) boot using/via PXE, - Btrfs, but, - CD, CD-ROM, - CUPS, (to) close sth., - computer*, configuration, - (to) configure, could, - Common Unix Printing System, (to) - deactivate sth., dialog, - directory, DVD, - e-book, EPUB, easy, - easily, end user, - etc., Ext3, - Ext4, flavor, flash - disk*, graphical user interface, - HTTP, if, - indexes, initialization, - (to) initialize, IPv4, - IPv6, license, (to) - license sth., lowercase, - just, need to, - might, (to) multitask, - must, obvious, - obviously, openSUSE, - (to) open sth., open source, - (to) print sth., (to) preconfigure - sth., preconfigured, (to) - press sth., PXE, PXE - boot, (to) quit sth., (to) - register, (to) register at sth., - (to) register for sth., SLE, - SLED, SLES, SUSE - Cloud, SUSE Linux Enterprise, - SUSE Linux Enterprise Desktop, SUSE - Linux Enterprise Server, SUSE Manager, - SUSE Studio, self-evident, - self-evidently, scrollbar*, - simple, simply, (to) select - sth., (to) shut sth. down, - shutdown, (to) start sth. up, - TAR archive*, (to) type sth. (into - sth.), usage, - Unix, uppercase, - when, want sth., - Wi-fi*, and YaST. - (An * marks potentially interesting changes.) - - - Changed accepted spellings of compund words whose second part is - name. These are now written with a space: file - name, host name, path - name, user name. - - - Changed accepted spelling from screen shot to - screenshot. - - - - - Switched from Merriam-Webster Collegiate - Dictionary to Web site as the - authoritative source of spellings. - - - Added to document how to use prompts - in screen elements. - - - In , added Geeko, Foxkeh, Konqi, and Duke - to the list of mascots to choose from. - - - Removed all occurrences of basically and - stuff. Removed other occurrences of colloquial language. - - - - Updated various examples to use newer software versions or to not - specify a software version. (Examples are soffice to - loffice, SUSE LINUX 9.1.4.2 to - SUSE Linux Enterprise). - - - Shortened and clarified many parts of the style guide to avoid - tautologies and unnecessary explanations. - - - Rewrote large parts of . Removed - example of structure. Added copyright notice as an example. Expanded on - information needed for title pages and imprints. - - - Removed differentiation between the many types of - authors files from . - This was too complicated to be practical. Also, current practice is to - never mention translators. - - - Added Objective before Instruction rule to . - - - Added short guideline about file extensions to . - - - Reworked to be more structured and - added instructions for preparing and editing screenshots. - - - Added . - - - More informative example in . - - - Simplified rules for creating IDs in . The - aim is to shorten the length of the average ID and to help to create - predictable IDs. - - - Added the co prefix to . - - - Added this list of changes as an appendix. - - - Added list of authors as a separate DocBook file. - - - Added standard entities as a separate file. - - - Updated copyright notice to refer to SUSE, LLC instead of Novell, - Inc. - - - - + + + + + Updated terminology table in . + + + + + Added entries for AOO, Apache + OpenOffice, Bluetooth, + Bluetooth card, drop-down + box, Ethernet card, + HTML page, HTTPS, + KDE, LibreOffice, + Linux, list box, + menu, OpenOffice.org, + OOo, please, + delta RPM, (to) save + sth. (with sub-entries), + selected, terminate, + text box, Wi-fi card, + Wi-fi/Bluetooth card, (to) write + sth. and video DVD. + + + + + Replaced entry for facilitate with entry + for simplify. + + + + + Added HTML web page as a rejected entry to + Web page. + + + + + Added joker as a rejected entry to + wild card. + + + + + Added screen as a rejected entry to + dialog. + + + + + Removed graphical UI as a rejected entry + from GUI and graphical user + interface. + + + + + Clarified usage of (to) close sth., + (to) log in, (to) log + out, and (to) quit sth.. + + + + + Changed accepted entry from Audio CD to + audio CD. + + + + + Removed entries for computer and + Kernel. + + + + + + + + 2014-02 + + + February 2014 Major Update + + + 2014-02 was a major update focused on restructuring the style guide and + adding terminology. Version 2014-02 was released on 2014-02-18. + + + + + Restructured large parts of the style guide + + + + + Removed Creating a Consistent Structure: Lessons for + Lizards section. + + + + + Renamed Creating a Consistent Structure: Official + SUSE Manuals to Outline of a + Manual and promoted to a + sect1. + + + + + Split the chapter Writing and Editing into + , + , and + . Moved the subsections of + Writing and Editing where they fit best. + + + + + Integrated the Markup appendix into to + and + . + + + + + Moved (formerly + Creating Procedures) and + (formerly + Presenting Computer Elements) as + subsections into . + + + + + Renamed Discriminatory Language to + . + + + + + Renamed Keys to + and promoted it to a + sect2 within + . + + + + + Renamed GUI Elements to + and promoted + it to a sect2 within + . + + + + + Created and moved + , + , and + as subsections into it. + + + + + Moved and the copyright + notice into separate DocBook files. + + + + + + + Restructured terminology list, added more terminology + + + + + Renamed Spelling Terms to + and moved it into + an appendix. + + + + + Centralized much of the information in the introductory + paragraph of Spelling Terms in + . + + + + + Change table layout from two columns (Word or + Phrase and Usage Guideline) to three + (Accepted, Rejected, and + Usage Guideline). + + + + + Added prefix (to) to all verbs. + + + + + Added grammatical classification of word to all entries. + + + + + Added entries for (to) activate sth., + add-on, advice, + (to) advise, after, + although, and, + appendixes, Audio CD, + because of, + basically, (to) boot using/via + PXE, Btrfs, + but, CD, + CD-ROM, CUPS, + (to) close sth., + computer*, + configuration, (to) + configure, could, + Common Unix Printing System, + (to) deactivate sth., + dialog, directory, + DVD, e-book, + EPUB, easy, easily, + end user, etc., + Ext3, Ext4, + flavor, flash disk*, + graphical user interface, + HTTP, if, + indexes, + initialization, (to) + initialize, IPv4, + IPv6, license, + (to) license sth., + lowercase, just, + need to, might, + (to) multitask, must, + obvious, obviously, + openSUSE, (to) open + sth., open source, + (to) print sth., (to) + preconfigure sth., + preconfigured, (to) press + sth., PXE, PXE + boot, (to) quit sth., + (to) register, (to) register at + sth., (to) register for sth., + SLE, SLED, + SLES, SUSE Cloud, + SUSE Linux Enterprise, SUSE + Linux Enterprise Desktop, SUSE Linux + Enterprise Server, SUSE + Manager, SUSE Studio, + self-evident, + self-evidently, + scrollbar*, simple, + simply, (to) select sth., + (to) shut sth. down, + shutdown, (to) start sth. + up, TAR archive*, + (to) type sth. (into sth.), + usage, Unix, + uppercase, when, + want sth., Wi-fi*, + and YaST. + + + (An * marks potentially interesting changes.) + + + + + Changed accepted spellings of compund words whose second part + is name. These are now written with a space: + file name, host name, + path name, user name. + + + + + Changed accepted spelling from screen shot + to screenshot. + + + + + + + Switched from Merriam-Webster Collegiate + Dictionary to + Web + site as the authoritative source of spellings. + + + + + Added to document how to use prompts + in screen elements. + + + + + In , added Geeko, Foxkeh, Konqi, and + Duke to the list of mascots to choose from. + + + + + Removed all occurrences of basically and + stuff. Removed other occurrences of colloquial + language. + + + + + Updated various examples to use newer software versions or to not + specify a software version. (Examples are + soffice to loffice, + SUSE LINUX 9.1.4.2 to SUSE Linux + Enterprise). + + + + + Shortened and clarified many parts of the style guide to avoid + tautologies and unnecessary explanations. + + + + + Rewrote large parts of . Removed + example of structure. Added copyright notice as an example. + Expanded on information needed for title pages and imprints. + + + + + Removed differentiation between the many types of + authors files from + . This was too complicated to be + practical. Also, current practice is to never mention translators. + + + + + Added Objective before Instruction rule to + . + + + + + Added short guideline about file extensions to + . + + + + + Reworked to be more structured and + added instructions for preparing and editing screenshots. + + + + + Added . + + + + + More informative example in . + + + + + Simplified rules for creating IDs in . The + aim is to shorten the length of the average ID and to help to + create predictable IDs. + + + + + Added the co prefix to + . + + + + + Added this list of changes as an appendix. + + + + + Added list of authors as a separate DocBook file. + + + + + Added standard entities as a separate file. + + + + + Updated copyright notice to refer to SUSE, LLC instead of Novell, + Inc. + + + + + diff --git a/xml/docu_styleguide.content.xml b/xml/docu_styleguide.content.xml index c7496311..f1981141 100644 --- a/xml/docu_styleguide.content.xml +++ b/xml/docu_styleguide.content.xml @@ -5,34 +5,31 @@ %entities; ]> - Documentation content - - - When selecting what to document, keep to the following guidelines: - - - - - - Do not promise future features. - Only document features that exist already or that will be finished before - the document is first published. - - - - - In some cases, it is appropriate to warn of scheduled future changes, - such as feature removals. - - - - - Documentation concerning unsupported features should be an exception. - When documenting an unsupported feature (usually a technology - preview), explain the support status before going into detail - about the feature. - - - - + Documentation content + + When selecting what to document, keep to the following guidelines: + + + + + Do not promise future features. Only document features that exist + already or that will be finished before the document is first + published. + + + + + In some cases, it is appropriate to warn of scheduled future changes, + such as feature removals. + + + + + Documentation concerning unsupported features should be an exception. + When documenting an unsupported feature (usually a technology + preview), explain the support status before going into + detail about the feature. + + + diff --git a/xml/docu_styleguide.contributors.xml b/xml/docu_styleguide.contributors.xml index 940990be..f709f36a 100644 --- a/xml/docu_styleguide.contributors.xml +++ b/xml/docu_styleguide.contributors.xml @@ -8,11 +8,10 @@ xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="sec-contributor"> - Contributors - - - For a list of people who contributed to this document, visit - the - Contributors page of our Git repository. - + Contributors + + For a list of people who contributed to this document, visit + the + Contributors page of our Git repository. + diff --git a/xml/docu_styleguide.language.xml b/xml/docu_styleguide.language.xml index 7a9d4081..4d9360ec 100644 --- a/xml/docu_styleguide.language.xml +++ b/xml/docu_styleguide.language.xml @@ -6,7 +6,6 @@ ]> Language - We write documentation in American English. Where spelling differences exist between American and British English, use the American English @@ -15,7 +14,6 @@ localise/localize), use the -ize variant. - When in doubt about the spelling or usage of a word, first see . If the usage of a word is not regulated @@ -23,21 +21,20 @@ ( for short). - - The correct spelling of &suse; product names is listed in the - terminology table () - and in the entities file of the Doc Kit repository at + The correct spelling of &suse; product names is listed in the terminology + table () and in the + entities file of the Doc Kit repository at . - If a product name is not listed in either spot, refer to the official &suse; - Products page and the - Marketing department. Make sure to not use articles in front of product names. + If a product name is not listed in either spot, refer to the official + &suse; Products + page and the Marketing department. Make sure to not use articles in front + of product names. When in doubt about a style rule, see The Chicago Manual of Style, 15th Edition. -
Abbreviations @@ -89,7 +86,6 @@
-
Biases and inclusiveness @@ -107,19 +103,18 @@ the initiative's Evaluation Framework and its Word lists. - - - The &suse; official terminology database, - TermWeb, also contains - inclusive naming recommendations. - - + + + The &suse; official terminology database, + TermWeb, also contains + inclusive naming recommendations. + + For more information about avoiding gender bias, see The Chicago Manual of Style, 5.43. For information about names of example items, see .
-
Capitalization of headings and titles
@@ -191,7 +186,6 @@
-
Commas @@ -205,7 +199,6 @@ configure a network connection.
-
Contractions @@ -213,7 +206,6 @@ purposefully writing a casual document.
-
Dashes @@ -224,7 +216,6 @@ spaces. Use em dashes sparingly.
-
End of sentence punctuation @@ -232,7 +223,6 @@ question marks to question and answer sections.
-
File and directory names @@ -285,7 +275,6 @@ words like PDF file, always capitalize the extension.
-
Headings @@ -304,7 +293,6 @@ .
-
Hyphens @@ -363,14 +351,12 @@ version and The calendar is up to date.
-
Lists For information about creating lists, see .
-
Numbers and measurements @@ -389,7 +375,6 @@ Style 9.6 and 9.16.
-
Possessives @@ -397,7 +382,6 @@ possessives of inanimate objects.
-
Prefixes @@ -410,7 +394,6 @@ .
-
Quotations @@ -464,7 +447,6 @@
-
Semicolons @@ -472,7 +454,6 @@ of commas in very complicated series.
-
Sentence structure @@ -491,7 +472,6 @@ click OK.
-
Slashes @@ -500,7 +480,6 @@ client/server.
-
Tense @@ -510,7 +489,6 @@ there. or Glibc is installed.
-
Tone and voice @@ -545,7 +523,6 @@ information (about), see.
-
Trademarks @@ -577,7 +554,6 @@ .
-
User interface items diff --git a/xml/docu_styleguide.manage.xml b/xml/docu_styleguide.manage.xml index ebd3006d..2e53c0be 100644 --- a/xml/docu_styleguide.manage.xml +++ b/xml/docu_styleguide.manage.xml @@ -5,351 +5,360 @@ %entities; ]> - Managing documents - - - This section provides an overview over features of XML you can use to - manage documents. - - -
- Remarks + Managing documents - Use remarks for editorial comments. Remarks can be placed within, before, - or after a para but must always be within a section element. When - creating output, remarks can be made visible in the output and thus help - within the editorial process. When creating the final output, deactivate - remarks. + This section provides an overview over features of XML you can use to + manage documents. - - Start remarks with your user name and the current date, then add a colon - (:) and finally your actual remark. To comment on - someone else's remark, add a new remark directly below it. Delete remarks - when the corresponding issue is resolved. - -<remark>tux (2013-10-13): could not find the option for foo</remark> -<remark>geeko (2013-11-02): see /usr/share/doc/foo.html</remark> - - You can add a - role - attribute with one of the following values to show the type of the - remark: - - - - - <tag class="attvalue">structure</tag> - - Use this type of remark to suggest changes to the text or XML - structure. - - - - - - <tag class="attvalue">language</tag> - - Use this type of remark to suggest language improvements. - - - - - - <tag class="attvalue">needinfo</tag> - - Use this type of remark to mark sections where you need input from - others, such as developers. - - - - - - <tag class="attvalue">trans</tag> - - Use this type of remark to give hints to translators. - - - - -
- -
- XML comments - - XML comments can be used for temporarily disabling portions of text. - Another use of XML comments is to create more permanent internal comments - or to mark up changes made for layout reasons. XML comments are never - visible in a publication. - -<!-- This is an XML comment. --> - - For information about formatting XML comments, see - . - -
- -
- Entities - - Entities are used to expand text. There are several situations in which - they can be used: - - - - - To represent special characters that cannot easily be displayed, - entered or memorized. - - - +
+ Remarks - To integrate external files using entities representing references to - their file names. + Use remarks for editorial comments. Remarks can be placed within, before, + or after a para but must always be within a section element. When + creating output, remarks can be made visible in the output and thus help + within the editorial process. When creating the final output, deactivate + remarks. - - - To repeat content easily. + Start remarks with your user name and the current date, then add a colon + (:) and finally your actual remark. To comment on + someone else's remark, add a new remark directly below it. Delete remarks + when the corresponding issue is resolved. - - - - When an entity is defined, it can be used in many places. - Entities increase consistency, as they only need to be defined once and will - automatically be expanded everywhere within the document. - - -
- Common types of entities - Official generic entities are maintained in the - Doc Kit repository. - They include &suse; product names and other terms that are valid for every - repository. In repositories configured with Doc Kit, the file - generic-entities.ent therefore must not - be changed (any changes will be overwritten by the next Doc Kit - run). If there is a need to declare a specific entity that applies - to the current repository only, this can be done - in the product-entities.ent or - entity-decl.ent file in the respective - repository. +<remark>tux (2013-10-13): could not find the option for foo</remark> +<remark>geeko (2013-11-02): see /usr/share/doc/foo.html</remark> - A generic-entities.ent or - entity-decl.ent file contains several categories of - entities: + You can add a role attribute with one of the + following values to show the type of the remark: - - - Products + - - All &suse; product names and other products and applications. - This helps when sudden name changes are necessary and avoids - misspellings. - + + <tag class="attvalue">structure</tag> + + Use this type of remark to suggest changes to the text or XML + structure. + + - - - Platforms - - Use entities for all hardware architectures referenced. - This helps when sudden name changes are necessary. - + + <tag class="attvalue">language</tag> + + Use this type of remark to suggest language improvements. + + - - - Books - - Title entities for all &suse; books. - This helps when sudden name changes are necessary. - + + <tag class="attvalue">needinfo</tag> + + Use this type of remark to mark sections where you need input from + others, such as developers. + + - - - General Entities - - Network IP addresses, host names and user names. - + + <tag class="attvalue">trans</tag> + + Use this type of remark to give hints to translators. + + - - + +
+
+ XML comments + + XML comments can be used for temporarily disabling portions of text. + Another use of XML comments is to create more permanent internal comments + or to mark up changes made for layout reasons. XML comments are never + visible in a publication. + +<!-- This is an XML comment. --> + + For information about formatting XML comments, see + . + +
+
+ Entities - There are several guidelines to consider when working with product - entities for &suse; documentation: + Entities are used to expand text. There are several situations in which + they can be used: - - - Entity selection + - - Use the entity name - productname - to identify the product for which the documentation is built. Set the - value of this entity once per release and have it expand to the name - of the current product: - - &productname; includes 389-ds. - - If you need to reference a specific subproduct or a different product, - use a more specific entity: - - Tuning &sle; for SAP + + To represent special characters that cannot easily be displayed, + entered or memorized. + - - - Acronyms - - In some cases (for example, limited space in table cells or in titles), - it is acceptable to use an entity for a product name acronym. Find the - approved entities for product name acronyms in the entity declaration - files, such as product-entities.ent or - generic-entities.ent. For a product name acronym, - you can use the generic entity productnameshort. - If you need acronym entities for specific products, they usually have an - appended a at the end, for example, - slsa for the acronym SLES. + + To integrate external files using entities representing references to + their file names. - - - Trademarks - - Follow the rules under and - . - + + To repeat content easily. + - - - If an entity is placed at the beginning of a phrase or title, its resolved - form is usually lowercase (unless specified in uppercase, for example, for product names). - To have it capitalized, use the phrase role="style:sentencecase" element. - For example: - <phrase role="style:sentencecase">ulp</phrase> - The entity ulp expands into User space live patching. - Never add this tag to the content within command and systemitem elements. - Capitalizing anything inside these elements makes the content ambiguous. - -
- -
- Using entity files - &suse; uses a set of custom entities. - Find these entities in the *.ent - files in each documentation repository. One entity file can include other entity files. - - - - Entity files are only used for original, English-language documents. - Translated documents contain only the resolved form of entities, - that is, plain-text directly in the document. - - - - - If you need a new entity to be used generically across all repositories, open a - pull request against generic-entities.ent in the Doc Kit - repository. After the change is approved by the Doc Kit maintainers, the entity - update for generic-entities.ent will be rolled out to all - Doc Kit-based repositories with the next Doc Kit run. - If you need a custom entity that only applies to a specific repository, define - it in product-entities.ent or in entities-decl.ent - in this specific repository. - Do not include custom entity definitions directly in the file header, - unless the custom definitions are needed to override externally embedded entities. - - - - - Use the UTF-8 encoding when editing and saving - the entity declaration file or any of the &suse; XML files. - - - - - Each header of a &suse; XML file includes the entity declaration file (by - means of an entity): - -<!ENTITY % entities SYSTEM "generic-entities.ent"> -%entities; - - Excerpt from <filename>product-entities.ent</filename> -<!ENTITYproduct-sp "1"> -<!ENTITY product-ga "15"> -<!ENTITY productnumber-regurl "&product-ga;.&product-sp;"> -<!ENTITY productnumber "<phrase xmlns='http://docbook.org/ns/docbook' role='productnumber'>15</phrase">"> - - + + + When an entity is defined, it can be used in many places. Entities + increase consistency, as they only need to be defined once and will + automatically be expanded everywhere within the document. + +
+ Common types of entities - Making an entity declaration. + Official generic entities are maintained in the + Doc Kit + repository. They include &suse; product names and other terms + that are valid for every repository. In repositories configured with + Doc Kit, the file generic-entities.ent therefore + must not be changed (any changes will be overwritten by the next Doc + Kit run). If there is a need to declare a specific entity that applies + to the current repository only, this can be done in the + product-entities.ent or + entity-decl.ent file in the respective repository. - - - Defining the entity name. + A generic-entities.ent or + entity-decl.ent file contains several categories + of entities: - - + + + Products + + + All &suse; product names and other products and applications. + This helps when sudden name changes are necessary and avoids + misspellings. + + + + + Platforms + + + Use entities for all hardware architectures referenced. This + helps when sudden name changes are necessary. + + + + + Books + + + Title entities for all &suse; books. This helps when sudden name + changes are necessary. + + + + + General Entities + + + Network IP addresses, host names and user names. + + + + - Setting the value which the processed entity should expand to. + There are several guidelines to consider when working with product + entities for &suse; documentation: - - + + + Entity selection + + + Use the entity name productname to + identify the product for which the documentation is built. Set + the value of this entity once per release and have it expand to + the name of the current product: + +&productname; includes 389-ds. + + If you need to reference a specific subproduct or a different + product, use a more specific entity: + +Tuning &sle; for SAP + + + + Acronyms + + + In some cases (for example, limited space in table cells or in + titles), it is acceptable to use an entity for a product name + acronym. Find the approved entities for product name acronyms in + the entity declaration files, such as + product-entities.ent or + generic-entities.ent. For a product name + acronym, you can use the generic entity + productnameshort. If you need + acronym entities for specific products, they usually have an + appended a at the end, for example, + slsa for the acronym + SLES. + + + + + Trademarks + + + Follow the rules under and + . + + + + - Using another entity within the entity value. - This entity reference is only valid if the other entity is defined - somewhere within the scope of the XML document that is built. - However, it does not matter whether the entity is defined before or - after the current entity definition. + If an entity is placed at the beginning of a phrase or title, its + resolved form is usually lowercase (unless specified in uppercase, for + example, for product names). To have it capitalized, use the + phrase role="style:sentencecase" element. + For example: - - +<phrase role="style:sentencecase">ulp</phrase> - Using a DocBook/GeekoDoc element within the entity value. - The attribute xmlns must be included to - define the correct XML namespace. + The entity ulp expands into User + space live patching. - - - -
-
- -
- XInclude elements - - XInclude elements are used to create modular source files that are easier - to work with and can be reused. When editing a book, create a new source - file for every chapter. Later, create a new GeekoDoc file that can serve as - the central point. In this file, use XInclude elements to reference all - chapters in the correct order: - + + Never add this tag to the content within + command and + systemitem elements. Capitalizing anything + inside these elements makes the content ambiguous. + +
+
+ Using entity files + + &suse; uses a set of custom entities. Find these entities in the + *.ent files in each documentation repository. One + entity file can include other entity files. + + + + + Entity files are only used for original, English-language + documents. Translated documents contain only the resolved form of + entities, that is, plain-text directly in the document. + + + + + If you need a new entity to be used generically across all + repositories, open a pull request against + generic-entities.ent in the Doc Kit + repository. After the change is approved by the Doc Kit + maintainers, the entity update for + generic-entities.ent will be rolled out to all + Doc Kit-based repositories with the next Doc Kit run. If you need a + custom entity that only applies to a specific repository, define it + in product-entities.ent or in + entities-decl.ent in this specific repository. + + + Do not include custom entity definitions directly in the file + header, unless the custom definitions are needed to override + externally embedded entities. + + + + + Use the UTF-8 encoding when editing and saving the entity + declaration file or any of the &suse; XML files. + + + + + Each header of a &suse; XML file includes the entity declaration file + (by means of an entity): + +<!ENTITY % entities SYSTEM "generic-entities.ent"> +%entities; + + Excerpt from <filename>product-entities.ent</filename> +<!ENTITYproduct-sp "1"> +<!ENTITY product-ga "15"> +<!ENTITY productnumber-regurl "&product-ga;.&product-sp;"> +<!ENTITY productnumber "<phrase xmlns='http://docbook.org/ns/docbook' role='productnumber'>15</phrase">"> + + + + Making an entity declaration. + + + + + Defining the entity name. + + + + + Setting the value which the processed entity should expand to. + + + + + Using another entity within the entity value. This entity + reference is only valid if the other entity is defined somewhere + within the scope of the XML document that is built. However, it + does not matter whether the entity is defined before or after the + current entity definition. + + + + + Using a DocBook/GeekoDoc element within the entity value. The + attribute xmlns must be included to + define the correct XML namespace. + + + + +
+
+
+ XInclude elements + + XInclude elements are used to create modular source files that are easier + to work with and can be reused. When editing a book, create a new source + file for every chapter. Later, create a new GeekoDoc file that can serve + as the central point. In this file, use XInclude elements to reference + all chapters in the correct order: + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="gfdl.xml"/> - - XInclude elements allow adding common sections to multiple books or - articles without having to maintain the text in multiple places. Common - sections include licenses and information on typographical conventions. - XIncludes also simplify co-editing documentation with others in a version - control system as they reduce the chance of merge conflicts. - - - By default, files referenced via XIncludes must be well-formed XML files that - are also valid GeekoDoc fragments. - This means that they must have a single top-level element and must not - contain elements that are not allowed in GeekoDoc. - Files that are supposed to be referenced multiple times from within the same - set, book or article must not contain any xml:id - attributes. - - - XIncludes also allow embedding plaintext files, for example, as the - content in screen elements. - To embed a plaintext file, add the attribute - parse="text" to the - xi:include element. - -
+ + XInclude elements allow adding common sections to multiple books or + articles without having to maintain the text in multiple places. Common + sections include licenses and information on typographical conventions. + XIncludes also simplify co-editing documentation with others in a version + control system as they reduce the chance of merge conflicts. + + + By default, files referenced via XIncludes must be well-formed XML files + that are also valid GeekoDoc fragments. This means that they must have a + single top-level element and must not contain elements that are not + allowed in GeekoDoc. Files that are supposed to be referenced multiple + times from within the same set, book or article must not contain any + xml:id attributes. + + + XIncludes also allow embedding plaintext files, for example, as the + content in screen elements. To embed a + plaintext file, add the attribute + parse="text" to the + xi:include element. + +
diff --git a/xml/docu_styleguide.name.xml b/xml/docu_styleguide.name.xml index f71376d3..369ea616 100644 --- a/xml/docu_styleguide.name.xml +++ b/xml/docu_styleguide.name.xml @@ -5,67 +5,60 @@ %entities; ]> - Names of example items - - - This section summarizes conventions for creating generic names for objects - in documentation. Most of the following names are covered through entities. - To check their spelling, refer to the Doc Kit repository at - . - See also . - - -
- Domains + Names of example items - Use and - as example domains. Both - domains were registered for use in documentation. + This section summarizes conventions for creating generic names for objects + in documentation. Most of the following names are covered through entities. + To check their spelling, refer to the Doc Kit repository at + . + See also . -
- -
- Host names - - Use objects of the solar system: For the most important system, use - sun. For other systems, use the names of - planets such as earth or - mars. - -
- -
- IPv4 addresses - - Use addresses from the class C subnet 192.168.255.0 - for examples. That is, replace the final 0 with any - integer between 0 and 255. To - create examples using a larger setup, use addresses from the private - network ranges. For more information, see - . - -
- -
- IPv6 addresses - - Use addresses from the subnet 2001:0db8::/32 for - examples. That is, after the 2001:0db8: prefix, add - six four-digit numbers, each separated by a colon on both sides. Each of - the hexadecimal digits may have a value between 0 and - f. A valid example URL is - 2001:0db8:0123:4567:89ab:cdef:1234:5678. - For more information, see - . - -
- -
- Users - - For example users, use free-software mascots, such as Tux (Linux Kernel), - Wilber (The GIMP), Geeko (&suse;), Foxkeh (Firefox), Konqi (KDE), or Duke - (Java). - -
+
+ Domains + + Use and + as example domains. Both + domains were registered for use in documentation. + +
+
+ Host names + + Use objects of the solar system: For the most important system, use + sun. For other systems, use the names of planets + such as earth or mars. + +
+
+ IPv4 addresses + + Use addresses from the class C subnet 192.168.255.0 + for examples. That is, replace the final 0 with any + integer between 0 and 255. To + create examples using a larger setup, use addresses from the private + network ranges. For more information, see + . + +
+
+ IPv6 addresses + + Use addresses from the subnet 2001:0db8::/32 for + examples. That is, after the 2001:0db8: prefix, add + six four-digit numbers, each separated by a colon on both sides. Each of + the hexadecimal digits may have a value between 0 and + f. A valid example URL is + 2001:0db8:0123:4567:89ab:cdef:1234:5678. For more + information, see + . + +
+
+ Users + + For example users, use free-software mascots, such as Tux (Linux Kernel), + Wilber (The GIMP), Geeko (&suse;), Foxkeh (Firefox), Konqi (KDE), or Duke + (Java). + +
diff --git a/xml/docu_styleguide.outline.xml b/xml/docu_styleguide.outline.xml index bd688de0..9e059b2a 100644 --- a/xml/docu_styleguide.outline.xml +++ b/xml/docu_styleguide.outline.xml @@ -5,94 +5,94 @@ %entities; ]> - Outline of a manual - - - Maintain a consistent structure within your documents. The structure can vary - between different books, articles or projects, but the most common parts of - the document structure are documented here. - - -
- Books + Outline of a manual - For books, use a document structure that includes the following elements, in - that order: + Maintain a consistent structure within your documents. The structure can + vary between different books, articles or projects, but the most common + parts of the document structure are documented here. - - +
+ Books - a preface + For books, use a document structure that includes the following elements, + in that order: - - - - chapters, split into sections - - - - - (optional) a glossary - - - - - (optional) appendixes - - - - - For books with many chapters, create parts at the outline level above - chapters. - - - - Title page and imprint - - - Both title page and imprint are created automatically, but depend on - information being present in the book. - - + - - Title - Work with the product manager to define the book title. The book title - should not contain the product name and version. + a preface - - - Product name and product version - Work with the product manager to find the correct product name and - version number. Mark this information up with - productname and - productnumber, respectively. + chapters, split into sections - - - Documentation version or revision information - Optionally, use the releaseinfo element to - mark up version or revision numbers of the documentation itself. + (optional) a glossary - - - Copyright notice - Use the standard copyright notice reproduced below. Change the - starting year of the copyright protection to the current year. + (optional) appendixes - - - Standard copyright notice + + + + For books with many chapters, create parts at the outline level above + chapters. + + + + Title page and imprint + + + Both title page and imprint are created automatically, but depend + on information being present in the book. + + + + + Title + + Work with the product manager to define the book title. The + book title should not contain the product name and version. + + + + + + Product name and product version + + Work with the product manager to find the correct product + name and version number. Mark this information up with + productname and + productnumber, respectively. + + + + + + Documentation version or revision information + + Optionally, use the releaseinfo + element to mark up version or revision numbers of the + documentation itself. + + + + + + Copyright notice + + Use the standard copyright notice reproduced below. Change + the starting year of the copyright protection to the current + year. + + + + Standard copyright notice <legalnotice> <para> Copyright &copy; [starting year]&ndash;<?dbtimestamp format="Y"?> @@ -122,200 +122,207 @@ consequences thereof. </para> </legalnotice> - - - - - - - Abstract - - - Use an abstract to summarize the information provided in a book, article, - chapter, or set in 70–150 characters. Do not use lists, images or - examples in an abstract. - - - An abstract - - Perform an upgrade of a &sle; system to a new major version in - environments which do not allow for standard booting of the - installation. - - - - - - Table of contents - - - The table of contents is generated automatically. - - - - - Preface - - - Include a brief overview of the content of a manual, related manuals and - typographical conventions. The preface can also contain information about - its target audience. - - - - - Parts - - - If you are writing a book with many chapters, create parts at the outline - level above chapters. Parts should contain at least three chapters. Keep - part titles clear and concise. Often a single noun is enough. Typical - part titles are Installation or - Network. - - - - - Chapters - - - Chapter titles should not contain product version numbers which affect - the output of data analytics. Chapters typically consist of the - following elements (appendixes should be regarded an exception): - - - - - Abstract - - In an abstract, summarize the topic instead of summarizing the - outline. See also + + + + + + Abstract + + + Use an abstract to summarize the information provided in a book, + article, chapter, or set in 70–150 characters. Do not use + lists, images or examples in an abstract. + + + An abstract + + Perform an upgrade of a &sle; system to a new major version in + environments which do not allow for standard booting of the + installation. + + + + + + Table of contents + + + The table of contents is generated automatically. + + + + + Preface + + + Include a brief overview of the content of a manual, related + manuals and typographical conventions. The preface can also contain + information about its target audience. + + + + + Parts + + + If you are writing a book with many chapters, create parts at the + outline level above chapters. Parts should contain at least three + chapters. Keep part titles clear and concise. Often a single noun + is enough. Typical part titles are + Installation or Network. + + + + + Chapters + + + Chapter titles should not contain product version numbers which + affect the output of data analytics. Chapters typically consist of + the following elements (appendixes should be regarded an + exception): + + + + + Abstract + + In an abstract, summarize the topic instead of summarizing + the outline. See also + . - cwickert 2021-12-09: The 70–155 chars range is taken from + cwickert 2021-12-09: The 70–155 chars range is taken from , we try to play it safe, thus reducing maximum character count by 5 to just 150. - - - + + + + + + Introduction + + Provide introductory information directly after the abstract. + Do not place it in a separate section. + + + + + + Sections + + Structure the detailed information, so readers can skim the + text. Create sections for every major task, such as + installing, configuring, monitoring, and administering. If + helpful, split sections into subsections. Avoid nesting + deeper than three levels of sections. + + + + Start sections with an introductory paragraph outlining the + focus of the section. If the section describes a sequential + task, add a procedure description, as discussed in + . Steps of a procedure can + contain a cross-reference to subsections where topical + background is provided and an action is explained in detail. + See also . + + + + + Troubleshooting + + In this section, collect common mistakes and problems. The + section should always be named + Troubleshooting. Use the DocBook element + qandaset (a Question and Answer + section) to mark up Troubleshooting + problems. In case you want to describe solutions to more than + ten problems, add topical subsections ( + qandadiv elements) below the + Troubleshooting section. + + + + + + More information + + In a section named More information, + collect Web links to all sources of information that might + prove helpful in a given context. Follow the general + referencing guidelines in + when creating such + sections. + + + + + + + + Glossary + + + The optional glossary contains important terms in alphabetical + order and provides a brief explanation for each. For more + information on creating lists of terms, see + . + + + + + Contributors + + + Writing documentation is a collaborative effort. To give credit to + all contributors, add an appendix to the guides which points to the + Contributors page for the respective GitHub + repository. For an example, see . + + + For articles and small documents (such as &suse; Best Practices) + whose content is created and maintained by five or fewer + contributors, all of whom are from outside the documentation team, + credit the contributors on the title page. + + + The above are a minimum. In addition, make sure that the + contributors appendix is compliant with the document license. + + + + +
+
+ Articles + + For articles, use a document structure that includes the following + elements, in that order: + + - - Introduction - Provide introductory information directly after the abstract. Do not - place it in a separate section. + introduction - - - Sections - Structure the detailed information, so readers can skim the text. - Create sections for every major task, such as installing, configuring, - monitoring, and administering. If helpful, split sections into - subsections. Avoid nesting deeper than three levels of sections. + sections, split into subsections - - - Start sections with an introductory paragraph outlining the focus of - the section. If the section describes a sequential task, add a - procedure description, as discussed in . - Steps of a procedure can contain a cross-reference to subsections where - topical background is provided and an action is explained in detail. - See also . - - - Troubleshooting - In this section, collect common mistakes and problems. The section - should always be named Troubleshooting. Use the - DocBook element qandaset (a Question and - Answer section) to mark up Troubleshooting - problems. In case you want to describe solutions to more than ten - problems, add topical subsections ( - qandadiv elements) below the - Troubleshooting section. + (optional) a glossary - - - More information - In a section named More information, collect - Web links to all sources of information that might prove helpful in a - given context. Follow the general referencing guidelines in - when creating such sections. + (optional) appendixes - - - - - - Glossary - - - The optional glossary contains important terms in alphabetical order and - provides a brief explanation for each. For more information on creating lists - of terms, see . - - - - - Contributors - - - Writing documentation is a collaborative effort. To give credit to all - contributors, add an appendix to the guides which points to the - Contributors page for the respective GitHub - repository. For an example, see . - - - For articles and small documents (such as &suse; Best Practices) whose - content is created and maintained by five or fewer contributors, all of - whom are from outside the documentation team, credit the contributors on - the title page. - - - The above are a minimum. In addition, make sure that the contributors - appendix is compliant with the document license. - - - - -
- -
- Articles - - For articles, use a document structure that includes the following elements, - in that order: - - - - - introduction - - - - - sections, split into subsections - - - - - (optional) a glossary - - - - - (optional) appendixes - - - -
+ +
diff --git a/xml/docu_styleguide.smartdocs.xml b/xml/docu_styleguide.smartdocs.xml index 80b01f2b..fe377495 100644 --- a/xml/docu_styleguide.smartdocs.xml +++ b/xml/docu_styleguide.smartdocs.xml @@ -8,253 +8,281 @@ xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:its="http://www.w3.org/2005/11/its" version="5.0" xml:id="sec-smartdocs"> - - Working with &sd; - - &sd; represent a modular approach to documentation whose goal is producing sets of - adaptable, solution-based, easy-to-find and reusable documents. - - - Rather than covering a complete technology or a set of problems, each &sd; article serves one - distinct purpose. Each article stands for itself, including requirements, context, instructions, - troubleshooting and FAQs. - - - &sd; consist of topics—smaller information units that can be reused in different contexts. - Four different topic types are provided: - - - - - Task topics instruct the user how to perform certain tasks. - - - - - Concept topics explain underlying concepts to the users. - - - - - Reference topics inform the user about basic facts (settings, options, parameters, etc.). - - - - - Glue topics help navigate complex topics and provide links to related information - (combine texts or structures that do not fit into any other category). Typical - glue topics include For more information and What's next sections. - Use glue topics to provide an additional layer of navigation for your article. - - - + Working with &sd; - Articles are built by bundling these topics into assembly files—organizational units to - structure the topics to create a coherent and meaningful document. + &sd; represent a modular approach to documentation whose goal is producing + sets of adaptable, solution-based, easy-to-find and reusable documents. - To create a &sd; project, use the templates for the assembly and its topical components - that are provided in the + + &sd; consist of topics—smaller information units that can be reused + in different contexts. Four different topic types are provided: + + + + + Task topics instruct the user how to perform certain tasks. + + + + + Concept topics explain underlying concepts to the users. + + + + + Reference topics inform the user about basic facts (settings, options, + parameters, etc.). + + + + + Glue topics help navigate complex topics and provide links to related + information (combine texts or structures that do not fit into any other + category). Typical glue topics include For more + information and What's next sections. Use glue + topics to provide an additional layer of navigation for your article. + + + + + Articles are built by bundling these topics into assembly + files—organizational units to structure the topics to create a + coherent and meaningful document. + + + To create a &sd; project, use the templates for the assembly and its + topical components that are provided in the + doc-modular repository. - -
- Using ITS tags with assemblies - Assembly files use ITS tags and attributes which flag whether the content of - the tag should be translated or not. In the following example, the ITS attribute indicates that the - content of the tag should not be translated: - +
+ Using ITS tags with assemblies + + Assembly files use ITS tags and attributes which flag whether the content + of the tag should be translated or not. In the following example, the ITS + attribute indicates that the content of the tag should not be translated: + <meta name="maintainer" content="Smart Doc author" its:translate="no"/> - -If the its:translate attribute is set to yes, translation is needed. - - - - - - - - - Element name - Description - Translation - - - - - - + + If the its:translate attribute is set to + yes, translation is needed. + + + + + + + + + Element name + Description + Translation + + + + + + <meta name="bugtracker" its:translate="no"> - - + + &suse;-specific info needed by the doc-manager tool and DAPS to process and build &suse; user documentation. - + No - - - - + + + + <phrase role="url">https://bugzilla.suse.com/enter_bug.cgi</phrase> - - + + &suse;-specific info needed by the doc-manager tool and DAPS to process and build &suse; user documentation. - No - - - - + No + + + + <phrase role="component">Non-product-specific documentation</phrase> - - + + &suse;-specific info needed by the doc-manager tool and DAPS to process and build &suse; user documentation. - + No - - - - + + + + <phrase role="product">&sd;</phrase> - - + + &suse;-specific info needed by the doc-manager tool and DAPS to process and build &suse; user documentation. - + No - - - - + + + + <phrase role="assignee">assignee@suse.com</phrase> - - + + &suse;-specific info needed by the doc-manager tool and DAPS to process and build &suse; user documentation. - + No - - - - + + + + <meta name="translation" its:translate="no"/> - - + + &suse;-specific info needed by the doc-manager tool and DAPS to process and build &suse; user documentation. - - - No - - - - - - + + + No + + + + + + <phrase role="trans">yes</phrase> - - + + &suse;-specific info needed by the doc-manager tool and DAPS to process and build &suse; user documentation. - No - - - - + No + + + + <phrase role="language">de-de,cs-cz</phrase> + + &suse;-specific info needed by the doc-manager tool and DAPS to process and build &suse; user documentation. - &suse;-specific info needed by the doc-manager tool and DAPS to process and build &suse; user documentation. - - No - - - - + No + + + + <meta name="architecture" content="x86;power" its:translate="no"/> - - + + &suse;-specific info needed by the doc-manager tool and DAPS to process and build &suse; user documentation. - No - - - - + No + + + + <meta name="productname" its:translate="no"/> - - + + The formal name of a product - No - - - - + No + + + + <productname version="15-SP5">&sles;</productname> - - + + A number assigned to a product - No - - - - + No + + + + <meta name="title" its:translate="yes"> short title for SEO and social media, max. 55 chars</meta> - - + + SEO-specific info. Adhere to the length limitations. - YesStick to the length limitations, min. 29 chars and max. 55 chars - - - - + + + Yes + + + Stick to the length limitations, min. 29 chars and max. 55 + chars + + + + + + <meta name="description" its:translate="yes"> short description, max. 150 chars</meta> - - + + SEO-specific info. Adhere to the length limitations. - YesStick to the length limitations, max. 150 chars - - - - + + + Yes + + + Stick to the length limitations, max. 150 chars + + + + + + <meta name="social-descr" its:translate="yes"> ultrashort description for social media, max. 55 chars</meta> - - + + SEO-specific info. Adhere to the length limitations. - YesStick to the length limitations, max. 55 chars - - - - Doc Manager tags: - + + + Yes + + + Stick to the length limitations, max. 55 chars + + + + + + + Doc Manager tags: + + <dm:docmanager xmlns:dm="urn:x-suse:ns:docmanager"> <dm:bugtracker> <dm:url>https://bugzilla.suse.com/enter_bug.cgi</dm:url> @@ -266,37 +294,44 @@ ultrashort description for social media, max. 55 chars</meta> <dm:translation>no</dm:translation> </dm:docmanager> - - - info: Wrapper to contain bibliographic + + info: Wrapper to contain bibliographic information about the content and other meta info. dm:PLACEHOLDER: &suse;-specific info needed by the doc-manager tool and DAPS to process and build &suse; user documentation. - No - - - - Resources: - + No + + + + + Resources: + + <resource xml:id="_glue-example" href="../glues/glue.xml"> <description>Glue example</description> </resource> - - + + &suse;-specific info needed by the doc-manager tool and DAPS to process and build &suse; user documentation. - - resourceNo - descriptionYes - - - - - Merge: - + + + resourceNo + + + descriptionYes + + + + + + + Merge: + + <merge> <title>Your title, limit to 55 characters, if possible</title> <subtitle>Subtitle if necessary</subtitle> @@ -322,50 +357,73 @@ ultrashort description for social media, max. 55 chars</meta> </merge> <title>You are a very special concept now!</title> - - - titleand subtitleYes, with length limitations (see above) - revhistoryNo - moduleNo - titleYes - - - - - -
- -
- Revision history - - A revision history lists all the high-level changes - about the document itself. It gives the reader an overview of important - changes made over time. - - Update revision history regularly, mentioning most important changes to - your document when you amend or rework it. The data you enter as revision history - is used as meta data. - The Revision History text is available as a link before the abstract and opens up in its individual - page. Keep in mind the following rules: - - - List revision entries in descending order by date. The latest entry must always come first. - - - Describe only significant changes that you performed. - - - If you have several changes of the same type (addition, change, removal), - group them under a dedicated itemizedlist. + + + + + titleand + subtitleYes, with length + limitations (see above) + + + revhistoryNo + + + moduleNo + + + titleYes + + + + + + +
+
+ Revision history + + A revision history lists all the high-level changes + about the document itself. It gives the reader an overview of important + changes made over time. + + + Update revision history regularly, mentioning most important changes to + your document when you amend or rework it. The data you enter as revision + history is used as meta data. The Revision History text is + available as a link before the abstract and opens up in its individual + page. Keep in mind the following rules: + + + + + List revision entries in descending order by date. The latest entry + must always come first. + + + + + Describe only significant changes that you performed. + + + + + If you have several changes of the same type (addition, change, + removal), group them under a dedicated + itemizedlist. + - Do not add links or references with xref of any kind. - If you want to mention a specific issue, use the abbreviations from and wrap it inside the tag uri. + + Do not add links or references with xref of any kind. If + you want to mention a specific issue, use the abbreviations from + + and wrap it inside the tag uri. - - - Revision history example (source) + + + Revision history example (source) <revhistory xml:id="rh-USE-ROOTID"> <revision><date>2024-11-13</date> @@ -393,35 +451,71 @@ ultrashort description for social media, max. 55 chars</meta> </revdescription> </revision> </revhistory> - - + + Revision history example (output) - + 2024-11-13 - - - Added sections: + + + + + Added sections: + - New section on foo to resolve issue bsc#12345 - New section on foo bar + + + New section on foo to resolve issue + bsc#12345 + + + + + New section on foo bar + + - Removed sections: + + + Removed sections: + - Removed section on foo1 to resolve issue bsc#12346 - Removed section on foo1 bar + + + Removed section on foo1 to resolve issue + bsc#12346 + + + + + Removed section on foo1 bar + + - Changed sections: + + + Changed sections: + - Changed section on foo2 to resolve issue bsc#12347 - Changed section on foo2 bar + + + Changed section on foo2 to resolve issue + bsc#12347 + + + + + Changed section on foo2 bar + + - +
diff --git a/xml/docu_styleguide.structure.xml b/xml/docu_styleguide.structure.xml index ae731357..4df1dda6 100644 --- a/xml/docu_styleguide.structure.xml +++ b/xml/docu_styleguide.structure.xml @@ -5,166 +5,156 @@ %entities; ]> - Structure and markup - - - This chapter contains instructions on using the correct DocBook markup - to create consistent and legible documents, and structuring the content in - the way that it effectively helps readers find answers to their queries. - - - In the Doc Kit repository, you can see examples of how - books - and articles - are rendered in our documentation. - - &suse; uses the GeekoDoc Relax NG schema which is compatible with DocBook 5.2. - For more information about the XML elements described here, see the - DocBook 5.2: The Definitive Guide sections listed in - . - - - - Important elements - - - - Element - Web link - - - - - - appendix - - - - - - - book - - - - - - - chapter - - - - - - - glossary - - - - - - - part - - - - - - - preface - - - - - - - sect1 - - - - - - -
- -
- Admonitory and advisory paragraphs + Structure and markup - To make readers aware of potential problems and recent changes, or to - give them tips, use an admonition element. Avoid using more than one - admonition per page of PDF output. + This chapter contains instructions on using the correct DocBook markup to + create consistent and legible documents, and structuring the content in the + way that it effectively helps readers find answers to their queries. - - - - <tag class="emptytag">warning</tag> - - Use these elements to warn of security issues, potential loss of data, - damage to hardware, or physical hazards. Warnings must always precede - the action to which they apply. - - - - - - <tag class="emptytag">important</tag> - - Use these elements to give vital information. - - - - - - <tag class="emptytag">tip</tag> - - Use these elements to introduce guidelines or give tips. - - - - - - <tag class="emptytag">note</tag> - - Use these elements to highlight software version differences. - - - - - Follow these rules when writing admonitions: + In the Doc Kit repository, you can see examples of how + books + and + articles + are rendered in our documentation. - - - - Add a - title - to admonitions. In the title, state the subject of the admonition and, - in the case of a - warning, also the source of danger. - - - - - warning or - important: - In the first paragraph, clearly state possible - consequences of ignoring the danger. - - - - - warning or - important: - In the second paragraph, explain how to avoid the danger. - If there are multiple ways to avoid a danger, use an unordered list. If - fewer than five consecutive steps must be taken to avoid a danger, - use an ordered list. If more than five consecutive steps need to be - taken, use a cross-reference to another part of the documentation. - - - - - An example of a warning (source) + + &suse; uses the GeekoDoc Relax NG schema which is compatible with DocBook + 5.2. For more information about the XML elements described here, see the + DocBook 5.2: The Definitive Guide sections listed in + . + + + Important elements + + + + Element + Web link + + + + + appendix + + + + + + book + + + + + + chapter + + + + + + glossary + + + + + + part + + + + + + preface + + + + + + sect1 + + + + + + +
+
+ Admonitory and advisory paragraphs + + To make readers aware of potential problems and recent changes, or to + give them tips, use an admonition element. Avoid using more than one + admonition per page of PDF output. + + + + + <tag class="emptytag">warning</tag> + + Use these elements to warn of security issues, potential loss of + data, damage to hardware, or physical hazards. Warnings must always + precede the action to which they apply. + + + + + + <tag class="emptytag">important</tag> + + Use these elements to give vital information. + + + + + + <tag class="emptytag">tip</tag> + + Use these elements to introduce guidelines or give tips. + + + + + + <tag class="emptytag">note</tag> + + Use these elements to highlight software version differences. + + + + + + Follow these rules when writing admonitions: + + + + + Add a title to admonitions. In the title, + state the subject of the admonition and, in the case of a + warning, also the source of danger. + + + + + warning or + important: In the first + paragraph, clearly state possible consequences of ignoring the + danger. + + + + + warning or + important: In the second + paragraph, explain how to avoid the danger. If there are multiple + ways to avoid a danger, use an unordered list. If fewer than five + consecutive steps must be taken to avoid a danger, use an ordered + list. If more than five consecutive steps need to be taken, use a + cross-reference to another part of the documentation. + + + + + An example of a warning (source) <warning> <title>Do not interrupt creation of file systems</title> <para> @@ -176,49 +166,45 @@ Always wait until formatting has finished. </para> </warning> - - - Do not interrupt creation of file systems - - Creating a file system can take multiple hours. Interrupting this - process will result in a corrupt file system and an unusable - installation. - - - Always wait until formatting has finished. - - -
- -
- Application names - - When referring to an application, add a - phrase role="productname" - element around it: - + + + Do not interrupt creation of file systems + + Creating a file system can take multiple hours. Interrupting this + process will result in a corrupt file system and an unusable + installation. + + + Always wait until formatting has finished. + + +
+
+ Application names + + When referring to an application, add a phrase + role="productname" element around it: + <phrase role="productname">LibreOffice</phrase> is an office suite. - - This will not result in a visual change but disables hyphenation in browsers. - This markup sidesteps hyphenation issues of CamelCased names. - -
- -
- Callouts - - Callouts allow annotating examples, such as configuration files or commands - with many options. - Add co - elements directly after the part of a screen that you want to annotate. - Do not try to align them above the part of a screen to annotate. Do not - use more than ten callouts per example. - - - See also . - - - Example of callouts (source) + + This will not result in a visual change but disables hyphenation in + browsers. This markup sidesteps hyphenation issues of CamelCased names. + +
+
+ Callouts + + Callouts allow annotating examples, such as configuration files or + commands with many options. Add co elements + directly after the part of a screen that you want to annotate. Do not try + to align them above the part of a screen to annotate. Do not use more + than ten callouts per example. + + + See also . + + + Example of callouts (source) <screen>color white/blue black/light-gray <co xml:id="co-color"/> default 0 <co xml:id="co-default"/></screen> <calloutlist> @@ -233,99 +219,99 @@ default 0 <co xml:id="co-default"/></screen> </para> </callout> </calloutlist> - - - Example of callouts (output) + + + Example of callouts (output) color white/blue black/light-gray default 0 - - - - Colors of the boot loader menu. - - - - - Defines the preselected option. - - - - - - Elements related to - <tag class="emptytag">callout</tag> - - - - Element - Web link - - - - - - - <tag class="emptytag">co</tag> - - Inline element to mark an area within a - screen. - - - - - - - - - - <tag class="emptytag">calloutlist</tag> - - Block element containing a list of descriptions for each of the - marked areas. - - - - - - - - - - <tag class="emptytag">callout</tag> - - Block element containing a description of a single area marked with - co. - - - - - - - - -
- - You can group different callouts to point to the same annotation. - This helps to avoid repeating the same annotation. - To do this, complete the following steps: - - - - Create the co element with the - xml:id attribute to comment on the first line. - - - - - On another line, use the xref element - to point to the ID from the previous step. - - - - - - Example of a callout group (source) - d1 = dict() <co xml:id="co-dict"/> + + + + Colors of the boot loader menu. + + + + + Defines the preselected option. + + + + + + Elements related to <tag class="emptytag">callout</tag> + + + + Element + Web link + + + + + + + <tag class="emptytag">co</tag> + + Inline element to mark an area within a + screen. + + + + + + + + + + <tag class="emptytag">calloutlist</tag> + + Block element containing a list of descriptions for each of + the marked areas. + + + + + + + + + + <tag class="emptytag">callout</tag> + + Block element containing a description of a single area + marked with co. + + + + + + + + +
+ + You can group different callouts to point to the same annotation. This + helps to avoid repeating the same annotation. To do this, complete the + following steps: + + + + + Create the co element with the + xml:id attribute to comment on the first + line. + + + + + On another line, use the xref element to + point to the ID from the previous step. + + + + + Example of a callout group (source) +d1 = dict() <co xml:id="co-dict"/> d2 = {} <xref linkend="co-dict"/> l1 = list() <co xml:id="co-list"/> l2 = [] <xref xml:id="co-list"/> @@ -337,428 +323,437 @@ default 0 <para>A list.</para> </callout> </calloutlist> - - - Example of a callout group (output) - d1 = dict() + + + Example of a callout group (output) +d1 = dict() d2 = {} l1 = list() l2 = [] - + - A dictionary. + + A dictionary. + - A list. + + A list. + - - -
- -
- Command-line input and command-line output - - When dealing with user input and system output shorter than 30 - characters, format it with an inline element, such as - command - or - filename. In all other cases, close the current - paragraph and enclose the user input and/or system output in a - screen - element. See also . - - - When using stand-alone command elements that - are outside of a screen, do not use - prompt elements before or within them. For - more information about prompt, see - . - - - Elements related to command-line input and output - - - - Element - Web link - - - - - - - <tag class="emptytag">screen</tag> - - Block element in which all characters are reproduced exactly as - they are in the source of the document. See also - . Can contain any of the inline - elements listed in this table. - - - - - - - - - - <tag class="emptytag">command</tag> - - Inline element that contains the name of an executable program or - the command that a user types to execute a program. Can contain - replaceable elements. - - - - - - - - - - <tag class="emptytag">option</tag> - - Inline element that contains an argument to a command or - instruction. Can contain - replaceable - elements. - - - - - - - - - - <tag class="emptytag">replaceable</tag> - - Inline element that contains content that can or must be replaced - by the user. - - - - - - - - - - <tag class="emptytag">filename</tag> - - Inline element that contains the name of a directory or file. Can - contain - replaceable - elements. - - - - - - - - - - <tag class="emptytag">varname</tag> - - Inline element that contains the name of a variable. Can contain - replaceable - elements. - - - - - - - - -
-
- Commands - - Commands can be embedded in running text or presented as part of a - screen environment. In running text, use - command - when referring to an actual command you would use on a command line: - + +
+
+ Command-line input and command-line output + + When dealing with user input and system output shorter than 30 + characters, format it with an inline element, such as + command or + filename. In all other cases, close the + current paragraph and enclose the user input and/or system output in a + screen element. See also + . + + + When using stand-alone command elements that + are outside of a screen, do not use + prompt elements before or within them. For + more information about prompt, see + . + + + Elements related to command-line input and output + + + + Element + Web link + + + + + + + <tag class="emptytag">screen</tag> + + Block element in which all characters are reproduced exactly + as they are in the source of the document. See also + . Can contain any of the inline + elements listed in this table. + + + + + + + + + + <tag class="emptytag">command</tag> + + Inline element that contains the name of an executable + program or the command that a user types to execute a + program. Can contain replaceable + elements. + + + + + + + + + + <tag class="emptytag">option</tag> + + Inline element that contains an argument to a command or + instruction. Can contain + replaceable elements. + + + + + + + + + + <tag class="emptytag">replaceable</tag> + + Inline element that contains content that can or must be + replaced by the user. + + + + + + + + + + <tag class="emptytag">filename</tag> + + Inline element that contains the name of a directory or file. + Can contain replaceable elements. + + + + + + + + + + <tag class="emptytag">varname</tag> + + Inline element that contains the name of a variable. Can + contain replaceable elements. + + + + + + + + +
+
+ Commands + + Commands can be embedded in running text or presented as part of a + screen environment. In running text, use + command when referring to an actual command + you would use on a command line: + To start LibreOffice from the command line, use <command>loffice</command>. - - Where options or subcommands belong with a command, include - them within the element command itself: - + + Where options or subcommands belong with a command, include them within + the element command itself: + To start LibreOffice Writer from the command line, use <command>loffice --writer</command>. - - If options or subcommands stand for themselves in a text, wrap them in the - element option. - - - Use markup for commands even inside - screen - environments. To avoid spelling or capitalization errors, whenever - possible, try commands before adding them to the documentation. - - - See also . - -
-
- File names - - A file name is the name of a file on a local or network disk. Can - contain a simple name or include a path or other elements specific - to the operating system. See also . - + + If options or subcommands stand for themselves in a text, wrap them in + the element option. + + + Use markup for commands even inside screen + environments. To avoid spelling or capitalization errors, whenever + possible, try commands before adding them to the documentation. + + + See also . + +
+
+ File names + + A file name is the name of a file on a local or network disk. Can + contain a simple name or include a path or other elements specific to + the operating system. See also . + Find the log file <filename>configuration.xml</filename> in the directory <filename>/etc/sysconfig</filename>. - - To assign standard names to files and images in DocBook and AsciiDoc, - follow the naming conventions at - . - -
-
- Literals - - Use - literal - to mark up data taken literally from a computer system. - + + To assign standard names to files and images in DocBook and AsciiDoc, + follow the naming conventions at + . + +
+
+ Literals + + Use literal to mark up data taken literally + from a computer system. + To create a comment, insert <literal>#</literal> characters. -
-
- Placeholders - - To mark up text that readers need to replace, use the - replaceable - element. Capitalize placeholder text in all contexts where this is not - detrimental to content intelligibility. - Do not use spaces within placeholders. Instead, use underscores - (_). - - To list the contents of a directory, execute +
+
+ Placeholders + + To mark up text that readers need to replace, use the + replaceable element. Capitalize placeholder + text in all contexts where this is not detrimental to content + intelligibility. Do not use spaces within placeholders. Instead, use + underscores (_). + +To list the contents of a directory, execute <command>ls <replaceable>DIRECTORY</replaceable></command>. -
-
- Prompts - - When documenting commands entered into Bash with a - screen - element, always prefix them with a prompt marked up this way: - +
+
+ Prompts + + When documenting commands entered into Bash with a + screen element, always prefix them with a + prompt marked up this way: + <prompt>&gt;&nbsp;</prompt><command>ls</command> - - To avoid making prompts longer than necessary, do not include paths, user - or host names, unless this is vital to understanding. - The first restricted user must always be named - tux. For more information about names of restricted - users, see . - - - Whenever you provide commands in a screen, - make it clear if the user needs regular or elevated privileges. - Avoid using root prompts in your documentation by using the - sudo command where applicable. If you do need a root - prompt, always mark it up as follows: - + + To avoid making prompts longer than necessary, do not include paths, + user or host names, unless this is vital to understanding. The first + restricted user must always be named tux. For more + information about names of restricted users, see + . + + + Whenever you provide commands in a screen, + make it clear if the user needs regular or elevated privileges. Avoid + using root prompts in your documentation by using the + sudo command where applicable. If you do need a root + prompt, always mark it up as follows: + <prompt role="root">#&nbsp;</prompt><command>yast</command> - - When documenting prompts other than the one of Bash, use a custom prompt - that is as generic as possible. - - - For consistency, it is helpful to create entities for the prompts used - in your documentation. Doc Kit repository contains entities for - user, root and sudo prompts. - For more information, see . - -
-
- Screens - - Screens are used to present: - - - - - long commands and commands together with their output - - - - - system output, such as system messages - - - - - code or configuration examples - - - + + When documenting prompts other than the one of Bash, use a custom + prompt that is as generic as possible. + + + For consistency, it is helpful to create entities for the prompts used + in your documentation. Doc Kit repository contains entities for + user, root and + sudo prompts. For more information, see + . + +
+
+ Screens + + Screens are used to present: + + + + + long commands and commands together with their output + + + + + system output, such as system messages + + + + + code or configuration examples + + + <screen><prompt>tux &gt; </prompt><command>ls /</command> bin dev lib mnt proc sbin suse usr boot etc lib64 mounts root selinux sys var data home lost+found opt run srv tmp</screen> - - - - Use screens only where necessary for understanding the documentation. - Present longer screens as examples. For more information, see - . - - - - - Do not add empty lines at the beginning or end of screens. They can - be cut away by the &suse; style sheets. However, most other - style sheets do not have such functionality. - - - - - Text in screens must not follow the indentation level of the XML around - them: All indentation will be reproduced verbatim. - - - - - Lines in a screen must be at most 80 characters long. If you are working - in a structure with less available space, such as within a list or within - a table, work with appropriate shorter line lengths. - - - - - Avoid command output that contains dates, version numbers, or other - version-specific information that frequently changes. - - - - - To make long shell commands less unwieldy, split them into multiple lines - at appropriate positions, such as after the end of an option. - At the end of each line but the last, append a \. - The character \ informs the shell that the command - invocation will continue after the end of the line. Splitting commands - into lines can also be helpful for aligning callouts with the right option. - - - - - You can combine multiple commands within a + + + Use screens only where necessary for understanding the + documentation. Present longer screens as examples. For more + information, see . + + + + + Do not add empty lines at the beginning or end of screens. They can + be cut away by the &suse; style sheets. However, most other style + sheets do not have such functionality. + + + + + Text in screens must not follow the indentation level of the XML + around them: All indentation will be reproduced verbatim. + + + + + Lines in a screen must be at most 80 characters long. If you are + working in a structure with less available space, such as within a + list or within a table, work with appropriate shorter line lengths. + + + + + Avoid command output that contains dates, version numbers, or other + version-specific information that frequently changes. + + + + + To make long shell commands less unwieldy, split them into multiple + lines at appropriate positions, such as after the end of an option. + At the end of each line but the last, append a + \. The character \ informs the shell + that the command invocation will continue after the end of the + line. Splitting commands into lines can also be helpful for + aligning callouts with the right option. + + + + + You can combine multiple commands within a + screen element, if: - - - - - all commands are explained unambiguously before the + + + + all commands are explained unambiguously before the + screen element and - - - - - all commands are strictly consecutive and none is optional. - - - - - In all other cases, do not combine multiple commands within one - screen element. Instead, use multiple - screen elements. For example, - as part of a multi-step procedure. - - - If you show multiple commands within a single - screen, use prompts before each command and - command elements around commands. This - effectively separates commands from each other and their output. - - - - - To work with long output, especially tabular output, use either of the - following strategies: - - - - - Remove or replace items that are irrelevant to your goal. - For example, replace long file names with shorter ones or remove a table - column and replace it with [...]. - - - - - Use a processing instruction at the beginning of the screen to decrease - font size: - - <?dbsuse-fo font-size="SIZEem"?> - - Replace SIZE with a suitable value, such - 0.7. Choose a value between 0.55 - and 1. Values outside that range will lead to either - unreadably small or unsuitably large text. - - - - - - To enable automatic syntax highlighting for programming languages or - formats, add a language - attribute for the respective language format. Valid language formats: - apache, bash, - c++, css, - diff, html, - xml, http, - ini, json, - java, javascript, - makefile, nginx, - php, perl, - python, ruby, - sql, crmsh, - dockerfile, lisp, - and yaml. - Note that syntax highlighting may not be supported in all - target formats. - - - - See also , , - , and . - -
-
- Variable names - - To reference to names of variables, use the - varname - element: - + + + + + all commands are strictly consecutive and none is optional. + + + + + In all other cases, do not combine multiple commands within one + screen element. Instead, use multiple + screen elements. For example, as part + of a multi-step procedure. + + + If you show multiple commands within a single + screen, use prompts before each command + and command elements around commands. + This effectively separates commands from each other and their + output. + + + + + To work with long output, especially tabular output, use either of + the following strategies: + + + + + Remove or replace items that are irrelevant to your goal. For + example, replace long file names with shorter ones or remove a + table column and replace it with [...]. + + + + + Use a processing instruction at the beginning of the screen to + decrease font size: + +<?dbsuse-fo font-size="SIZEem"?> + + Replace SIZE with a suitable value, + such 0.7. Choose a value between + 0.55 and 1. Values + outside that range will lead to either unreadably small or + unsuitably large text. + + + + + + + To enable automatic syntax highlighting for programming languages + or formats, add a language attribute + for the respective language format. Valid language formats: + apache, + bash, c++, + css, diff, + html, xml, + http, ini, + json, java, + javascript, + makefile, + nginx, php, + perl, + python, + ruby, sql, + crmsh, + dockerfile, + lisp, and + yaml. + + + Note that syntax highlighting may not be supported in all target + formats. + + + + + See also , , + , and . + +
+
+ Variable names + + To reference to names of variables, use the + varname element: + To select another display manager, start the YaST system configuration editor and change the value of <varname>DISPLAYMANAGER</varname>. +
-
- -
- Cross-references - - Use the xref - element (read: cross ref) when referring to an appendix, - chapter, example, figure, part, preface, section, table or question and - answer set. The element referenced needs to have an - xml:id attribute, an identifier. Create - identifiers to reference from cross-references using the rules - under . Note that the xref - element only works when it links to documentation within the same set, - for example, the same book or set of books. - - Other types of references to resources are described in - and . - - Example of a cross-reference (source) - <sect2 xml:id="sec-cross-reference"> +
+ Cross-references + + Use the xref element (read: cross + ref) when referring to an appendix, chapter, example, figure, + part, preface, section, table or question and answer set. The element + referenced needs to have an xml:id + attribute, an identifier. Create identifiers to reference from + cross-references using the rules under . Note + that the xref element only works when it + links to documentation within the same set, for example, the same book or + set of books. + + + Other types of references to resources are described in + and . + + + Example of a cross-reference (source) +<sect2 xml:id="sec-cross-reference"> <title>Cross-references</title> <para> Use the <sgmltag class="emptytag">xref</sgmltag> element ... @@ -768,88 +763,92 @@ and change the value of <varname>DISPLAYMANAGER</varname>. See <xref linkend="sec-cross-reference"/>. </para> </sect2> - - - Example of a cross-reference (output) - - See . - - - - This example shows the default display of a cross-reference. To change it, use the - xrefstyle attribute, either with - select: or template:. Do not use custom - named xrefstyle attributes that require support - from the style sheets. For more info, refer to DocBook XSL: The Complete - Guide: Customizing cross-references. - - - Keep in mind the following cases where listing cross-references is discouraged and must be - avoided: - + + + Example of a cross-reference (output) + + See . + + + + This example shows the default display of a cross-reference. To change + it, use the xrefstyle attribute, either with + select: or + template:. Do not use custom + named xrefstyle attributes + that require support from the style sheets. For more info, refer to + DocBook + XSL: The Complete Guide: Customizing cross-references. + + + Keep in mind the following cases where listing cross-references is + discouraged and must be avoided: + - - Do not insert cross-references (xref linkend="...") - into a title element. - The title must not be clickable, and a cross-reference in a title can create - issues when linking to such a title in a different paragraph. + + Do not insert cross-references (xref + linkend="...") into a title + element. The title must not be clickable, and a cross-reference in a + title can create issues when linking to such a title in a different + paragraph. + - Do not create references to paragraphs (para) or - other elements that have no title. An exception to this rule is the - element step to which you may create - references. If a reference to an element without a title is vital - to the document, use the attribute xreflabel - to assign a title. - + Do not create references to paragraphs + (para) or other elements that have no + title. An exception to this rule is the element + step to which you may create references. + If a reference to an element without a title is vital to the + document, use the attribute xreflabel to + assign a title. + + - Do not prefix or suffix cross-references with text labels such - as appendix, chapter, table, - or figure. Such labels are generated automatically. + + Do not prefix or suffix cross-references with text labels such as + appendix, chapter, table, or + figure. Such labels are generated automatically. +
- -
- Emphasis - - Where possible, indicate stress with language only. If that is not - possible, use the - emphasis - element to indicate stress. - - - Where added emphasis is needed, use the - role="bold" - attribute. - +
+ Emphasis + + Where possible, indicate stress with language only. If that is not + possible, use the emphasis element to + indicate stress. + + + Where added emphasis is needed, use the + role="bold" attribute. + This will be displayed in <emphasis>italics</emphasis>. This will be displayed in <emphasis role="bold">bold</emphasis> -
- -
- Examples - - Use examples to illustrate complex processes. The rules established in - also apply to examples. - - - Examples usually contain screen elements. - Additionally, there can be callouts and explanatory text. - - - Always give examples a title and an identifier. - - - For more information about screen environments, see - . - For more information about displaying computer input and output, see - . To annotate examples, use callouts. - Callouts are described in . - - - Example of an example +
+
+ Examples + + Use examples to illustrate complex processes. The rules established in + also apply to examples. + + + Examples usually contain screen elements. + Additionally, there can be callouts and explanatory text. + + + Always give examples a title and an identifier. + + + For more information about screen environments, see + . For more information about displaying + computer input and output, see . To + annotate examples, use callouts. Callouts are described in + . + + + Example of an example <example xml:id="ex-example"> <title>Example of an example</title> <screen><prompt>tux &gt; </prompt><command>ps -xa</command> @@ -858,336 +857,338 @@ will be displayed in <emphasis role="bold">bold</emphasis> 5172 ? S 0:02 kdeinit: kdesktop 5174 ? S 0:04 kdeinit: kicker</screen> </example> - - - Elements related to - <tag class="emptytag">example</tag> - - - - Element - Web link - - - - - - - <tag class="emptytag">example</tag> - - Formal block element containing a - title - and a - screen - or other elements such as lists or paragraphs. - - - - - - - - - - <tag class="emptytag">screen</tag> - - Verbatim block element for displaying text that readers might see - on a computer terminal or in a text file. - - - - - - - - -
-
- -
- External links - - Information that is relevant within &suse; documentation is often - available from other Web sites already. - In such cases, choose between linking to these sites or including their - content in edited form. - Adhere to the following guidelines when selecting sites to link to: - - - + + + Elements related to <tag class="emptytag">example</tag> + + + + Element + Web link + + + + + + + <tag class="emptytag">example</tag> + + Formal block element containing a + title and a + screen or other elements such as + lists or paragraphs. + + + + + + + + + + <tag class="emptytag">screen</tag> + + Verbatim block element for displaying text that readers might + see on a computer terminal or in a text file. + + + + + + + + +
+
+
+ External links - Link to credible sources, such as suse.com, upstream projects or - developer sites. - Avoid linking to direct competitors of &suse;. - Do not link to obvious clickbait sites. + Information that is relevant within &suse; documentation is often + available from other Web sites already. In such cases, choose between + linking to these sites or including their content in edited form. Adhere + to the following guidelines when selecting sites to link to: - - + + + + Link to credible sources, such as suse.com, upstream projects or + developer sites. Avoid linking to direct competitors of &suse;. Do + not link to obvious clickbait sites. + + + + + Prefer larger, well-kept sites over blogs that may vanish overnight. + If you need to link to smaller blogs, save an archive version of the + site at . + + + + + Avoid linking to sites that feature controversial or political + content. + + + - Prefer larger, well-kept sites over blogs that may vanish overnight. - If you need to link to smaller blogs, save an archive version of the - site at . + In some cases, product managers will request avoiding all or selected + external links to avoid issues for customers impacted by restrictive + firewall rules. - - - Avoid linking to sites that feature controversial or political content. + Use the link element to mark up URLs that can + be opened with a Web browser, such as + . Always add the correct + protocol prefix (for example, https://), otherwise + links will not work. If possible, use the secure protocol prefix + (https://). - - - - In some cases, product managers will request avoiding all or selected - external links to avoid issues for customers impacted by restrictive - firewall rules. - - - Use the - link - element to mark up URLs that can be opened with a Web browser, such as - . Always add the correct - protocol prefix (for example, https://), otherwise - links will not work. If possible, use the secure protocol prefix - (https://). - - - Never use filename - for a link, as that would both disable the link checker and make the link - unclickable. Avoid entering a text label between - link - start and end tags. Instead, use a self-closing tag: - -<link xlink:href="https://www.example.org/"/> - - Make URLs as short as possible before adding them to documentation. Many - long URLs can be shortened by leaving away non-essential pieces, - such as the _utm parameters used for marketing purposes. - If a Web site provides a built-in URL shortener, use it. - - - Do not use third-party URL shorteners, such as bit.ly. - Third-party URL shorteners have the following disadvantages: - - - - They obscure the destination a link points to. + Never use filename for a link, as that would both disable the + link checker and make the link unclickable. Avoid entering a text label + between link start and end tags. Instead, use + a self-closing tag: - - +<link xlink:href="https://www.example.org/"/> - They introduce an extra element of uncertainty, as the shortening - service may disappear or become unreliable in the future. + Make URLs as short as possible before adding them to documentation. Many + long URLs can be shortened by leaving away non-essential pieces, such as + the _utm parameters used for marketing purposes. If a + Web site provides a built-in URL shortener, use it. - - - The providers of these services usually run Web analytics that may - introduce privacy issues. + Do not use third-party URL shorteners, such as bit.ly. Third-party URL + shorteners have the following disadvantages: - - - - Do not use - link - to link to &suse; documentation outside of the current document set. - Instead, use the appropriate entity for the book title. Always reference - the book itself, as chapter names can change. - - - For consistency, do not use the article in front of the name of the - referenced book or chapter. For example, The general concept of Podman is - described in Containers and Podman. - - - Where possible, collect links in a More information section - at the end of the chapter. - This helps readers focus on your - documentation instead of leading them immediately to other resources. - This is described in . - - - To mark up multiple links, create an - itemizedlist - around them. Do not use a list environment for a single link. If you need - to present many links, group them by topic and create a separate list - environment for each group. Provide a comprehensive title for each of the - groups or an introductory sentence. For more information about creating lists, - see . - - - Where possible, provide translators with localized versions of links in - the comments of the source file. - - - Other types of references to resources are described in - and - . - -
- -
- External links to &suse; documentation - - The &suse; documentation is hosted under documentation.suse.com. - This is the URL that must be provided in all documents. The abbreviated URLs such - as doc.suse.com and docs.suse.com also work but must - be avoided for SEO reasons. - - - Make sure to use complete URLs instead of entities for an easy copy and paste. - - - Most links in our documentation that goes to documentation.suse.com - refer to a specific product and release. However, sometimes it makes sense to - not include the SP or even the major release. - These are so-called SP-independent links. - - - The following reasons give you an idea when to use them: - - - + + + + They obscure the destination a link points to. + + + + + They introduce an extra element of uncertainty, as the shortening + service may disappear or become unreliable in the future. + + + + + The providers of these services usually run Web analytics that may + introduce privacy issues. + + + - Your linked information is independent from any SP + Do not use link to link to &suse; + documentation outside of the current document set. Instead, use the + appropriate entity for the book title. Always reference the book itself, + as chapter names can change. - - - You cannot or do not need to pick a specific SP + For consistency, do not use the article in front of the name of the + referenced book or chapter. For example, The general concept of + Podman is described in Containers and + Podman. - - - You want to link to the most recent SP without checking which one it is + Where possible, collect links in a More information + section at the end of the chapter. This helps readers focus on your + documentation instead of leading them immediately to other resources. + This is described in . - - - - You want to support SEO where the most prominent SP is more important - than previous, older SPs + + To mark up multiple links, create an + itemizedlist around them. Do not use a list + environment for a single link. If you need to present many links, group + them by topic and create a separate list environment for each group. + Provide a comprehensive title for each of the groups or an introductory + sentence. For more information about creating lists, see + . - - - - Make sure to follow this syntax: - - documentation.suse.com/<PRODUCT>[/<MAJOR_RELEASE>]/<DEEP_LINK> - - The placeholders mean the following: - - - - PRODUCT: the abbreviation of the product, like sle for &sle;, - sle-ha for &sle; Server High Availability Extension, etc. + Where possible, provide translators with localized versions of links in + the comments of the source file. - - - MAJOR_RELEASE: an optional major release like 12 or 15. If you omit it, - your link will be redirected to use the most recent release. + Other types of references to resources are described in + and + . - - +
+
+ External links to &suse; documentation - DEEP_LINK: the link that points to a specific chapter or section within a book + The &suse; documentation is hosted under + documentation.suse.com. This is the URL that must be provided + in all documents. The abbreviated URLs such as doc.suse.com + and docs.suse.com also work but must be avoided for SEO + reasons. - - - - Make sure you use html and not single-html. This - is needed for SEO reasons. - - - For example, the link - - points to the System requirements for &sle; Server High Availability Extension. To turn this link into an - SP-independent link, you need to identify the different components first: - - - - PRODUCT is sle-ha + Make sure to use complete URLs instead of entities for an easy copy and + paste. - - - MAJOR_RELEASE is 15 (no SP mentioned) + Most links in our documentation that goes to + documentation.suse.com refer to a specific product and + release. However, sometimes it makes sense to not + include the SP or even the major release. These are so-called + SP-independent links. - - - DEEP_LINK is /html/SLE-HA-all/article-installation.html#sec-ha-inst-quick-req + The following reasons give you an idea when to use them: - - - - With the above parts, the redirection rules on our server allow expressing - SP-independent links in several ways: - - - - - https://documentation.suse.com/sle-ha-15/html/SLE-HA-all/article-installation.html#sec-ha-inst-quick-req - - Redirects to the most recent SP for the major release 15 - - - - https://documentation.suse.com/sle-ha/html/SLE-HA-all/article-installation.html#sec-ha-inst-quick-req - - Redirects to the most recent major release, latest SP available - - - - - If IDs have been changed between releases or SPs, this is what happens: - - - - - If the hash part (everything after #) is not found, the browser will jump - to the beginning of the file. - - - - - If the file cannot be found (in our example, article-installation.html), - the server will respond with a 404 error (file not found). - - - - -
- -
- Figures - - For figures within lists or procedures, use the - informalfigure - element. In all other cases, use the - figure - element. Always assign an - xml:id - attribute to - figure - elements. Reference figures from the text by means of a cross-reference. - For more information, see . - - - All referenced image files must have a lowercase alphanumeric file name. - When specifying figure names, follow the naming conventions at - . - - - Provide an appropriate image width using the width - attribute. For both figure types, formal and informal, always add a - textobject role="description" - as in to provide an alternative text for the - HTML output. - - - Example of a figure + + + + Your linked information is independent from any SP + + + + + You cannot or do not need to pick a specific SP + + + + + You want to link to the most recent SP without checking which one it + is + + + + + You want to support SEO where the most prominent SP is more important + than previous, older SPs + + + + + Make sure to follow this syntax: + +documentation.suse.com/<PRODUCT>[/<MAJOR_RELEASE>]/<DEEP_LINK> + + The placeholders mean the following: + + + + + PRODUCT: the abbreviation of the product, + like sle for &sle;, sle-ha for &sle; + Server High Availability Extension, etc. + + + + + MAJOR_RELEASE: an optional major release + like 12 or 15. If you omit it, your link will be redirected to use + the most recent release. + + + + + DEEP_LINK: the link that points to a + specific chapter or section within a book + + + + + Make sure you use html and not + single-html. This is needed for SEO reasons. + + + For example, the link + + points to the System requirements for &sle; Server High + Availability Extension. To turn this link into an SP-independent link, + you need to identify the different components first: + + + + + PRODUCT is sle-ha + + + + + MAJOR_RELEASE is 15 (no SP mentioned) + + + + + DEEP_LINK is + /html/SLE-HA-all/article-installation.html#sec-ha-inst-quick-req + + + + + With the above parts, the redirection rules on our server allow + expressing SP-independent links in several ways: + + + + + https://documentation.suse.com/sle-ha-15/html/SLE-HA-all/article-installation.html#sec-ha-inst-quick-req + + + Redirects to the most recent SP for the major release 15 + + + + + https://documentation.suse.com/sle-ha/html/SLE-HA-all/article-installation.html#sec-ha-inst-quick-req + + + Redirects to the most recent major release, latest SP available + + + + + + If IDs have been changed between releases or SPs, this is what happens: + + + + + If the hash part (everything after #) is not found, the browser + will jump to the beginning of the file. + + + + + If the file cannot be found (in our example, + article-installation.html), the server will respond with a 404 + error (file not found). + + + + +
+
+ Figures + + For figures within lists or procedures, use the + informalfigure element. In all other cases, + use the figure element. Always assign an + xml:id attribute to + figure elements. Reference figures from the + text by means of a cross-reference. For more information, see + . + + + All referenced image files must have a lowercase alphanumeric file name. + When specifying figure names, follow the naming conventions at + . + + + Provide an appropriate image width using the + width attribute. For both figure types, + formal and informal, always add a textobject + role="description" as in to provide an + alternative text for the HTML output. + + + Example of a figure <figure xml:id="fig-picture"> <title>An interesting picture</title> <mediaobject> @@ -1202,264 +1203,268 @@ will be displayed in <emphasis role="bold">bold</emphasis> </textobject> </mediaobject> </figure> - - - Elements related to - <tag class="emptytag">figure</tag> - - - - Element - Web link - - - - - - - <tag class="emptytag">figure</tag> - - Formal block element containing a - title - and a - mediaobject. - - - - - - - - - - <tag class="emptytag">informalfigure</tag> - - Informal block element containing a - mediaobject. - - - - - - - - - - <tag class="emptytag">mediaobject</tag> - - Block element containing one or more - imageobject - elements. Place additional textual descriptions inside - textobject - elements. - - - - - - - - - - <tag class="emptytag">imageobject</tag> - - Element containing - imagedata - and meta information about the image. - - - - - - - - - - <tag class="emptytag">imagedata</tag> - - Element that points to an external image file. - - - - - - - - - - <tag class="emptytag">textobject</tag> - - Element containing textual description of a media object as a - fallback option. - - - - - - - - -
-
- Graphics - - Keep graphics as simple as possible. Use as little text as possible. To - allow for translation, reserve twice as much space for runs of text as - the English version of it consumes. - + + + Elements related to <tag class="emptytag">figure</tag> + + + + Element + Web link + + + + + + + <tag class="emptytag">figure</tag> + + Formal block element containing a + title and a + mediaobject. + + + + + + + + + + <tag class="emptytag">informalfigure</tag> + + Informal block element containing a + mediaobject. + + + + + + + + + + <tag class="emptytag">mediaobject</tag> + + Block element containing one or more + imageobject elements. Place + additional textual descriptions inside + textobject elements. + + + + + + + + + + <tag class="emptytag">imageobject</tag> + + Element containing imagedata and + meta information about the image. + + + + + + + + + + <tag class="emptytag">imagedata</tag> + + Element that points to an external image file. + + + + + + + + + + <tag class="emptytag">textobject</tag> + + Element containing textual description of a media object as a + fallback option. + + + + + + + + +
+
+ Graphics + + Keep graphics as simple as possible. Use as little text as possible. To + allow for translation, reserve twice as much space for runs of text as + the English version of it consumes. + +
+
+ Screenshots + + Use screenshots to illustrate complex situations in which the user + cannot easily follow the instructions otherwise. + + + + + Be selective. Only illustrate steps in which meaningful user + interactions are necessary. Do not create screenshots of progress + bars or confirmation windows. Usually, it is unnecessary to create + a screenshot of every step of an instruction. + + + + + Always create screenshots illustrating the situation right before + an action has been taken. + + + + + Insert screenshots directly after the textual description of the + action. + + + + + Make sure screenshots focus on what they are supposed to + illustrate. When documenting application windows, create a + screenshot of the window only. When documenting Web applications, + only reproduce the contents of the tab instead of the entire + browser window. + + + + + Do not scale screenshots using graphics software. Embed screenshots + at their original resolution and use DocBook attributes to scale + them appropriately. + + + + + Avoid creating screenshots of windows higher or wider than + 800 pixels at 96 pixels per inch. When creating + screenshots of applications scaled for a higher pixel-per-inch + count, apply a proportionally larger maximum window size. + + + + + To ensure readability and consistency, scale screenshots with the + width attribute. Choose the appropriate scaling + from the following list: + + + + + Screenshots of the whole desktop should be scaled to + 90–99% page width. + + + + + Screenshots of individual application windows should be scaled + to 75–99% page width. + + + + + Small windows such as message boxes should be scaled to + 50–60% page width. + + + + + + + Create screenshots that are recognizable to readers. For example, + create screenshots of KDE applications on a KDE desktop with the + default KDE theme and disable toolbar modifications you have made. + + + + + Use grayscale font antialiasing (default on &suse; operating + systems). Subpixel font antialiasing (default on Windows and macOS + operating systems) creates colored letter edges when zoomed or + printed. + + + + + Where applicable, follow the rules in . + + + + + Avoid editing screenshots. To anonymize portions of a screenshot, + pixelize it. To highlight parts of a screenshot, use rectangles or + arrows. Never add callouts, text or freely drawn objects. Always + select colors that provide a good contrast with their background. + + + + + If possible, avoid screenshots with dates, version numbers, or + other version-specific information that frequently changes. + + + +
-
- Screenshots - - Use screenshots to illustrate complex situations in which the user - cannot easily follow the instructions otherwise. - - - - - Be selective. Only illustrate steps in which meaningful user - interactions are necessary. Do not create screenshots of progress bars - or confirmation windows. Usually, it is unnecessary to create a - screenshot of every step of an instruction. - - - - - Always create screenshots illustrating the situation right before an - action has been taken. - - - - - Insert screenshots directly after the textual description of the - action. - - - - - Make sure screenshots focus on what they are supposed to illustrate. - When documenting application windows, create a screenshot of the - window only. When documenting Web applications, only reproduce the - contents of the tab instead of the entire browser window. - - - - - Do not scale screenshots using graphics software. Embed screenshots at - their original resolution and use DocBook attributes to scale them - appropriately. - - - - - Avoid creating screenshots of windows higher or wider than - 800 pixels at 96 pixels per inch. When creating - screenshots of applications scaled for a higher pixel-per-inch count, - apply a proportionally larger maximum window size. - - - - - To ensure readability and consistency, scale screenshots with the - width attribute. Choose the appropriate scaling from - the following list: - - - - - Screenshots of the whole desktop should be scaled to 90–99% - page width. - - +
+ Glossaries + + An optional glossary contains terms and their definitions. Make sure that + the glossary entries are appropriate to the intended audience. Define + unfamiliar terms and special jargon. + + + Define infinitive forms of verbs and singular nouns. Do not start the + definition with the term itself. Use lowercase for the term unless it is + a proper noun. + + + Where applicable, group your terms with the + glossdiv tag for higher ordering. + + + To support automatic alphabetical ordering in localized versions, use + glosslist so that glossary items are sorted + in alphabetical order by default. + + + Use cross-references in the following cases: + + - - Screenshots of individual application windows should be scaled to - 75–99% page width. - + + To direct the reader to another glossary entry, use the + glosssee tag. This is helpful, for + example, when linking acronyms with their written out forms. + - - Small windows such as message boxes should be scaled to - 50–60% page width. - + + To provide the reader with additional information about related + glossary entries, use glossseealso. + - - - - - Create screenshots that are recognizable to readers. For example, - create screenshots of KDE applications on a KDE desktop with the - default KDE theme and disable toolbar modifications you have made. - - - - - Use grayscale font antialiasing (default on &suse; operating systems). - Subpixel font antialiasing (default on Windows and macOS operating - systems) creates colored letter edges when zoomed or printed. - - - - - Where applicable, follow the rules in . - - - - - Avoid editing screenshots. - To anonymize portions of a screenshot, pixelize it. - To highlight parts of a screenshot, use rectangles or arrows. - Never add callouts, text or - freely drawn objects. Always select colors that provide a good - contrast with their background. - - - - - If possible, avoid screenshots with dates, version numbers, or other - version-specific information that frequently changes. - - - -
-
- -
- Glossaries - - An optional glossary contains terms and their definitions. Make sure that - the glossary entries are appropriate to the intended audience. Define - unfamiliar terms and special jargon. - - - Define infinitive forms of verbs and singular nouns. Do not start the definition with the term itself. - Use lowercase for the term unless it is a proper noun. - - Where applicable, group your terms with the glossdiv - tag for higher ordering. - To support automatic alphabetical ordering in localized versions, use - glosslist so that glossary items are sorted in alphabetical order by default. - - Use cross-references in the following cases: - - - - To direct the reader to another glossary entry, use the glosssee - tag. This is helpful, for example, when linking acronyms with their written out forms. - - - - To provide the reader with additional information about related glossary entries, - use glossseealso. - - - - - The markup for a glossary entry is shown in - . - - - A typical example of a glossary + + + The markup for a glossary entry is shown in + . + + + A typical example of a glossary <glossary xmlns="http://docbook.org/ns/docbook" version="5.2"> <title>Glossary</title> @@ -1490,525 +1495,463 @@ will be displayed in <emphasis role="bold">bold</emphasis> </glossentry> </glossary> - - -
- -
- Identifiers - - - - Always use an - xml:id - attribute in parts, chapters, appendixes, sections, figures, glossaries and - examples. Identifiers can be used in other elements as well, for example, - block elements, such as tables and procedures. - - - - - In identifiers, only use lowercase basic Latin alphabetic and numeric - characters and - (hyphen). Follow the regex pattern - [\-0-9a-zA-Z]+. Do not use _ - and . characters, as they may hurt search engine - optimization. - - - - - Identifiers can consist of multiple parts. Join these parts with a - - (hyphen). - - - - - Prefix - - Signifies the type of XML element. - Prefixes aid writers in creating logically named identifiers for - elements. - Use identifiers in accordance with . - - - - Do not add prefixes to identifiers for XML elements that are used to - determine the name of HTML pages (such as section and chapter elements). - Such exposure of identifiers can hurt SEO. - - - - - Chapter title label - - Shortened version of the title of the parent chapter or parent - chapter-level element (preface, appendix, etc.). Do not add a - chapter title label to chapters and chapter-level elements - themselves. Do not add chapter title identifiers within articles. - - - - - - Element title label - - Shortened version of name of the title of the element itself. - - - - - - Examples of identifiers + +
+
+ Identifiers + + + + Always use an xml:id attribute in parts, + chapters, appendixes, sections, figures, glossaries and examples. + Identifiers can be used in other elements as well, for example, block + elements, such as tables and procedures. + + + + + In identifiers, only use lowercase basic Latin alphabetic and numeric + characters and - (hyphen). Follow the regex + pattern [\-0-9a-zA-Z]+. Do not use + _ and . characters, as they may + hurt search engine optimization. + + + + + Identifiers can consist of multiple parts. Join these parts with a + - (hyphen). + + + + + Prefix + + Signifies the type of XML element. Prefixes aid writers in + creating logically named identifiers for elements. Use + identifiers in accordance with . + + + + Do not add prefixes to identifiers for XML elements that are used + to determine the name of HTML pages (such as section and chapter + elements). Such exposure of identifiers can hurt SEO. + + + + + Chapter title label + + Shortened version of the title of the parent chapter or parent + chapter-level element (preface, appendix, etc.). Do not add a + chapter title label to chapters and chapter-level elements + themselves. Do not add chapter title identifiers within + articles. + + + + + + Element title label + + Shortened version of name of the title of the element itself. + + + + + + Examples of identifiers xml:id="pro-install-sles" xml:id="install-yast" xml:id="tab-install-source" - - - - - Use short, memorable, English terms or phrases as title labels. Favor - longer terms over non-obvious abbreviations. Always use the singular of - nouns and the infinitive of verbs. For example, a section about - installing with YaST could be - called install-yast. - - - A figure in that section showing language selection could use the - identifier fig-install-yast-language. - - - + + + + + Use short, memorable, English terms or phrases as title labels. Favor + longer terms over non-obvious abbreviations. Always use the singular + of nouns and the infinitive of verbs. For example, a section about + installing with YaST could be + called install-yast. + + + A figure in that section showing language selection could use the + identifier fig-install-yast-language. + + + + + Keep in mind that section and chapter identifiers are used in the + online documentation URLs. Choosing understandable keywords helps + readers to understand what the page is about and also improves the + search engine ranking. + + + - Keep in mind that section and chapter identifiers are used - in the online documentation URLs. Choosing understandable keywords helps - readers to understand what the page is about and also improves the - search engine ranking. + Do not rework identifiers in existing documentation, instead apply these + rules to newly created documentation only. - - - - Do not rework identifiers in existing documentation, instead apply these - rules to newly created documentation only. - - - Abbreviations for different elements in an - <tag class="attribute">xml:id</tag> - attribute - - - - Element - Prefix - - - - - - appendix - - - No prefix - - - - - book - - - No prefix - - - - - co - - - co - - - - - chapter - - - No prefix - - - - - example - - - ex - - - - - figure - - - fig - - - - - glossary - - - No prefix - - - - - glossterm - - - gl - - - - - itemizedlist - - - il - - - Only add an - xml:id - attribute when the list has a - title - element - - - - - - - listitem - - - li - - - - - indexterm - - - idx - - - Only add when creating index ranges - - - - - - - orderedlist - - - ol - - - - - part - - - No prefix - - - - - preface - - - No prefix - - - - - procedure - - - pro - - - - - qandaset, +
+ Abbreviations for different elements in an <tag class="attribute">xml:id</tag> attribute + + + + Element + Prefix + + + + + appendix + + No prefix + + + + book + + No prefix + + + + co + + co + + + + chapter + + No prefix + + + + example + + ex + + + + figure + + fig + + + + glossary + + No prefix + + + + glossterm + + gl + + + + itemizedlist + + il + + + Only add an xml:id attribute when the list has a + title element + + + + + + listitem + + li + + + + indexterm + + idx + + + Only add when creating index ranges + + + + + + orderedlist + + ol + + + + part + + No prefix + + + + preface + + No prefix + + + + procedure + + pro + + + + qandaset, qandadiv, qandaentry - - - qa - - - - - sect1, + + qa + + + + sect1, sect2, etc., section - - - No prefix - - - - - set - - - No prefix - - - - - step - - - st - - - - - table - - - tab - - - - - topic - - - No prefix - - - - - variablelist - - - vl - - - - - varlistentry - - - vle - - - - -
-
- -
- Lists - - &suse; documentation uses the following types of lists (the respective XML - elements are given in parentheses): - - - - - Itemized lists (itemizedlist). - Also known as bullet lists or unordered lists. - - - - - Ordered lists (orderedlist). - Also known as numbered lists. - - - - - Variable lists (variablelist). - Also known as definition lists or description lists. - - - - - Procedures (procedure). - Also known as step-by-step instructions or step lists. - Described in . - - - - - Follow these rules when creating or editing lists: - - - - - Always introduce a list in the text. If needed for reference or better - coordination with the related text, add a title and an - xml:id - attribute. - - - + + No prefix + + + + set + + No prefix + + + + step + + st + + + + table + + tab + + + + topic + + No prefix + + + + variablelist + + vl + + + + varlistentry + + vle + + + + + +
+
+ Lists - A list must contain at least two items. If items are few, short and simple - in structure, consider incorporating them in the flowing text instead - of creating a list. + &suse; documentation uses the following types of lists (the respective + XML elements are given in parentheses): - - + + + + Itemized lists (itemizedlist). Also known + as bullet lists or unordered lists. + + + + + Ordered lists (orderedlist). Also known + as numbered lists. + + + + + Variable lists (variablelist). Also known + as definition lists or description lists. + + + + + Procedures (procedure). Also known as + step-by-step instructions or step lists. Described in + . + + + - If all list items are nouns only, do not capitalize their first letter. - Use sentence-style capitalization for list items that are full sentences - and for terms in descriptive lists. + Follow these rules when creating or editing lists: - - + + + + Always introduce a list in the text. If needed for reference or + better coordination with the related text, add a title and an + xml:id attribute. + + + + + A list must contain at least two items. If items are few, short and + simple in structure, consider incorporating them in the flowing text + instead of creating a list. + + + + + If all list items are nouns only, do not capitalize their first + letter. Use sentence-style capitalization for list items that are + full sentences and for terms in descriptive lists. + + + + + Use a period after every list item that is a sentence. Do not use a + period after the items that are not complete sentences. Use either + all full sentences in your bullet lists or all fragments. Avoid a + mix. + + + Do not use commas and semicolons to end punctuation. + + + + + Wherever possible, use parallel phrasing and grammatical construction + between list items. This provides a pattern that makes it easier to + follow the text. + + + + + Lists are visually distinct and can break up text flow. Do not + overuse them. + + + - Use a period after every list item that is a sentence. Do not use a period - after the items that are not complete sentences. Use either all - full sentences in your bullet lists or all fragments. Avoid a mix. - - Do not use commas and semicolons to end punctuation. + Never nest more than three lists within each other. Instead, restructure + the information using a combination of lists and running texts. - - - Wherever possible, use parallel phrasing and grammatical construction - between list items. - This provides a pattern that makes it easier to follow the text. - - - - - Lists are visually distinct and can break up text flow. - Do not overuse them. + To be able to reference untitled lists, use the + xreflabel attribute. For more information, + see . - - - - Never nest more than three lists within each other. - Instead, restructure the information using a combination of lists and running - texts. - - - To be able to reference untitled lists, use the - xreflabel - attribute. For more information, see . - - - Elements related to lists - - - - Element - Web link - - - - - - - <tag class="emptytag">itemizedlist</tag> - - Block element for an unordered list. Contains multiple - listitem - elements. - - - - - - - - - - <tag class="emptytag">orderedlist</tag> - - Block element for a numbered list. Contains multiple - listitem - elements. - - - - - - - - - - <tag class="emptytag">variablelist</tag> - - Block element for a descriptive list. Contains multiple - varlistentry - elements. - - - - - - - - - - <tag class="emptytag">varlistentry</tag> - - Element within a - variablelist - that associates a - term - and a - listitem. - - - - - - - - - - <tag class="emptytag">term</tag> - - Element whose content serves as the title of an element of a - variablelist. - - - - - - - - - - <tag class="emptytag">listitem</tag> - - A single list element. To add text to this item, first add a - para - element. - - - - - - - - -
-
- Itemized lists - - Use itemized lists whenever the order of list items is irrelevant. - They are often used to provide an overview of information or - to introduce or summarize information. - - - Example of an itemized list (source) + + Elements related to lists + + + + Element + Web link + + + + + + + <tag class="emptytag">itemizedlist</tag> + + Block element for an unordered list. Contains multiple + listitem elements. + + + + + + + + + + <tag class="emptytag">orderedlist</tag> + + Block element for a numbered list. Contains multiple + listitem elements. + + + + + + + + + + <tag class="emptytag">variablelist</tag> + + Block element for a descriptive list. Contains multiple + varlistentry elements. + + + + + + + + + + <tag class="emptytag">varlistentry</tag> + + Element within a variablelist + that associates a term and a + listitem. + + + + + + + + + + <tag class="emptytag">term</tag> + + Element whose content serves as the title of an element of a + variablelist. + + + + + + + + + + <tag class="emptytag">listitem</tag> + + A single list element. To add text to this item, first add a + para element. + + + + + + + + +
+
+ Itemized lists + + Use itemized lists whenever the order of list items is irrelevant. They + are often used to provide an overview of information or to introduce or + summarize information. + + + Example of an itemized list (source) <para> The following operating systems are supported: </para> @@ -2024,38 +1967,37 @@ xml:id="tab-install-source" </para> </listitem> </itemizedlist> - - - Example of an itemized list (output) - - The following operating systems are supported: - - - - - Linux, Kernel 2.4 and newer - - - + + + Example of an itemized list (output) + + The following operating systems are supported: + + + + + Linux, Kernel 2.4 and newer + + + + + FreeBSD 7 and newer + + + + +
+
+ Ordered lists - FreeBSD 7 and newer + Use ordered lists when items have a strict order, hierarchy or + importance. Do not use ordered lists to describe sequential user + actions (step-by-step instructions). For sequential user actions, use a + procedure, as described in . If order is + not relevant, use an itemized list or a variable list. - - - -
-
- Ordered lists - - Use ordered lists when items have a strict order, hierarchy or importance. - Do not use ordered lists to describe sequential user actions (step-by-step - instructions). - For sequential user actions, use a procedure, as described in - . - If order is not relevant, use an itemized list or a variable list. - - - Example of an ordered list (source) + + Example of an ordered list (source) <para> Before installing, make sure of the following: </para> @@ -2066,375 +2008,361 @@ xml:id="tab-install-source" </para> </listitem> <listitem> - <para> - The latest security updates are installed. - If you are in doubt, run an online update. - </para> - </listitem> -</orderedlist> - - - Example of an ordered list (output) - - Before installing, make sure of the following: - - - - - The network connection of the computer is configured properly. - - - - - The latest security updates are installed. If you are in doubt, run - an online update. - - - - -
-
- Variable lists - - Use variable lists when defining terms or describing options. - Each item of a variable list contains a short term that is then further - explained by means of an explanatory paragraph. - - - Use sentence-style capitalization for both the term and the list item. - - - To reference the list, assign it a xml:id - attribute and add a title. - Individual list items may be referenced by assigning an - xml:id. The entry is then identified by the value - of - xml:id - and referenced by the term. - - - Example of a variable list (source) -<para> - This book consists of several parts: -</para> -<variablelist> - <varlistentry> - <term>Installation</term> - <listitem> - <para> - Learn about the installation and initial configuration of a Linux system. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>System</term> - <listitem> - <para> - Get a basic understanding of the system components. - </para> - </listitem> - </varlistentry> -</variablelist> - - - Example of a variable list (output) - - This book consists of several parts: - - - - Installation - - - Learn about the installation and initial configuration of a Linux - system. - - - - - System - - - Get a basic understanding of the system components. - - - - - -
-
- -
- Keys and key combinations - - Capitalize all keys as printed on a standard keyboard. Capitalize all letter - keys. To refer to a capitalized character, - use Z, - for example. Introduce this convention by means of the - Typographical Conventions section of the introduction. - - - To mark up key combinations, use - keycombo - as a wrapper for multiple - keycap - elements. Separators between - keycap - elements are then created automatically. - - - If a key is listed in , use the - function - attribute with the appropriate value. When using the - function - attribute, make the tag self-closing—DocBook's language files - will insert key names automatically. This simplifies both your work and - the work of translators. - - - For more information about creating cross-references, see - . - - - Example of a key -To create a screenshot, press <keycap>Print Screen</keycap>. - - - Example of a keyboard combination -To save a file, press -<keycombo><keycap function="control"/><keycap>S</keycap></keycombo>. - - - Elements related to - <tag class="emptytag">keycap</tag> - - - - Element - Web link - - - - - - - <tag class="emptytag">keycombo</tag> - - Inline element containing multiple - keycap - elements that together make up a key combination. - - - - - - - - - - <tag class="emptytag">keycap</tag> - - Inline element to mark up a single key. Contains either the key - labels text inside it or is self-closing and has a - function - attribute with one of the following values: - - - - - - alt - - - - - backspace - - - - - command - - - - - control - - - - - delete - - - - - down - - - - - end - - - - - enter - - - - - escape - - - - - home - - - - - insert - - - - - left - - - - - meta - (also known as Win, Windows or - Super) - - - - - option - (macOS only) - - - - - pagedown - - - - - pageup - - - - - right - - - - - shift - - - - - space - - - - - tab - - - - - up - - - - - - - - - -
-
- -
- Outline levels and sectioning - - Create sections using the - sect1, sect2 and - sect3 elements. - Avoid outlines that require sect4 - and sect5 elements. - Instead, create a flatter structure in which more elements are - visible at a glance. - - - Provide at least one paragraph of introductory information directly within - each section. - - - Do not create lone subsections. A lone subsection is a section that is - the only subsection of its parent section. - - - For more information about writing headlines, see - . - -
- -
- Procedures - - Use procedures to describe sequential tasks. A procedure consists of the - following elements and attributes: - - - + <para> + The latest security updates are installed. + If you are in doubt, run an online update. + </para> + </listitem> +</orderedlist> + + + Example of an ordered list (output) + + Before installing, make sure of the following: + + + + + The network connection of the computer is configured properly. + + + + + The latest security updates are installed. If you are in doubt, + run an online update. + + + + +
+
+ Variable lists + + Use variable lists when defining terms or describing options. Each item + of a variable list contains a short term that is then further explained + by means of an explanatory paragraph. + + + Use sentence-style capitalization for both the term and the list item. + + + To reference the list, assign it a xml:id + attribute and add a title. Individual list items may be referenced by + assigning an xml:id. The entry is then + identified by the value of xml:id and + referenced by the term. + + + Example of a variable list (source) +<para> + This book consists of several parts: +</para> +<variablelist> + <varlistentry> + <term>Installation</term> + <listitem> + <para> + Learn about the installation and initial configuration of a Linux system. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>System</term> + <listitem> + <para> + Get a basic understanding of the system components. + </para> + </listitem> + </varlistentry> +</variablelist> + + + Example of a variable list (output) + + This book consists of several parts: + + + + Installation + + + Learn about the installation and initial configuration of a + Linux system. + + + + + System + + + Get a basic understanding of the system components. + + + + + +
+
+
+ Keys and key combinations - An - xml:id - attribute. + Capitalize all keys as printed on a standard keyboard. Capitalize all + letter keys. To refer to a capitalized character, use + Z, for + example. Introduce this convention by means of the Typographical + Conventions section of the introduction. - - - A title. + To mark up key combinations, use keycombo as + a wrapper for multiple keycap elements. + Separators between keycap elements are then + created automatically. - - - An introductory phrase establishing the purpose of the procedure. If - the procedure is otherwise the only element in its section, place the - introductory phrase before the procedure. + If a key is listed in , use the + function attribute with the appropriate + value. When using the function attribute, + make the tag self-closing—DocBook's language files will insert key + names automatically. This simplifies both your work and the work of + translators. - - - If there are preconditions or prerequisites, add them as a second - paragraph after the introduction. + For more information about creating cross-references, see + . - - + + Example of a key +To create a screenshot, press <keycap>Print Screen</keycap>. + + + Example of a keyboard combination +To save a file, press +<keycombo><keycap function="control"/><keycap>S</keycap></keycombo>. + + + Elements related to <tag class="emptytag">keycap</tag> + + + + Element + Web link + + + + + + + <tag class="emptytag">keycombo</tag> + + Inline element containing multiple + keycap elements that together + make up a key combination. + + + + + + + + + + <tag class="emptytag">keycap</tag> + + Inline element to mark up a single key. Contains either the + key labels text inside it or is self-closing and has a + function attribute with one of + the following values: + + + + + + alt + + + + + backspace + + + + + command + + + + + control + + + + + delete + + + + + down + + + + + end + + + + + enter + + + + + escape + + + + + home + + + + + insert + + + + + left + + + + + meta (also known as + Win, Windows or + Super) + + + + + option (macOS only) + + + + + pagedown + + + + + pageup + + + + + right + + + + + shift + + + + + space + + + + + tab + + + + + up + + + + + + + + + +
+
+
+ Outline levels and sectioning - Short, simple steps and, if necessary, substeps describing the actions - to be performed. See also . + Create sections using the sect1, + sect2 and sect3 + elements. Avoid outlines that require sect4 + and sect5 elements. Instead, create a flatter + structure in which more elements are visible at a glance. - - - - To link alternative actions inside the same substep element, use - or. Apply a - performance=optional - attribute to optional steps. - - - Steps may contain a link to an explanatory subsection providing further - details on the step. - - - Example of a procedure (source) + + Provide at least one paragraph of introductory information directly + within each section. + + + Do not create lone subsections. A lone subsection is a section that is + the only subsection of its parent section. + + + For more information about writing headlines, see + . + +
+
+ Procedures + + Use procedures to describe sequential tasks. A procedure consists of the + following elements and attributes: + + + + + An xml:id attribute. + + + + + A title. + + + + + An introductory phrase establishing the purpose of the procedure. If + the procedure is otherwise the only element in its section, place the + introductory phrase before the procedure. + + + + + If there are preconditions or prerequisites, add them as a second + paragraph after the introduction. + + + + + Short, simple steps and, if necessary, substeps describing the + actions to be performed. See also + . + + + + + To link alternative actions inside the same substep element, use + or. Apply a + performance=optional attribute to optional + steps. + + + Steps may contain a link to an explanatory subsection providing further + details on the step. + + + Example of a procedure (source) <procedure xml:id="pro-procedure"> <title>Example of a procedure</title> <para> @@ -2458,215 +2386,214 @@ xml:id="tab-install-source" </para> </step> </procedure> - - - Example of a procedure (output) - - To add a new user to the system, perform the following steps: - - - - In the YaST window, click - User and group management. - - - - - To open the Add a new user dialog, click - Add. - - - - - Type in the user name and click Create. - - - - - Elements related to - <tag class="emptytag">procedure</tag> - - - - Element - Web link - - - - - - - <tag class="emptytag">procedure</tag> - - Block element containing a - title - (optional) and multiple - step - elements. - - - - - - - - - - <tag class="emptytag">step</tag> - - Element signifying a single unit of action. Usually contains a - para - element, but can also house a - substeps - element. - - - - - - - - - - <tag class="emptytag">substeps</tag> - - Element containing multiple, subordinate - step - elements. - - - - - - - - -
-
- -
- Products - - Always use the preferred product name instead of, for example, an - acronym. When referring to a product, add a - phrase role="productname" - element around it. This will not result in a visual change but disables - hyphenation: - + + + Example of a procedure (output) + + To add a new user to the system, perform the following steps: + + + + In the YaST window, click + User and group management. + + + + + To open the Add a new user dialog, click + Add. + + + + + Type in the user name and click Create. + + + + + Elements related to <tag class="emptytag">procedure</tag> + + + + Element + Web link + + + + + + + <tag class="emptytag">procedure</tag> + + Block element containing a title + (optional) and multiple step + elements. + + + + + + + + + + <tag class="emptytag">step</tag> + + Element signifying a single unit of action. Usually contains + a para element, but can also + house a substeps element. + + + + + + + + + + <tag class="emptytag">substeps</tag> + + Element containing multiple, subordinate + step elements. + + + + + + + + +
+
+
+ Products + + Always use the preferred product name instead of, for example, an + acronym. When referring to a product, add a phrase + role="productname" element around it. This will not result in a + visual change but disables hyphenation: + <phrase role="productname">LibreOffice</phrase> is an office suite. -
- -
- Profiling - - Profiling is convenient for the creation of consistent documentation - across different products or product lines. This is especially beneficial - when similar products share a considerable amount of features, with only - a few differences. Instead of maintaining separate documentation for - each product, you can share most of the XML source code and only vary text - snippets where necessary. In DocBook XML files, you can mark some elements - as conditional by using profiling attributes. Specify which conditions - apply to the output when processing the files to generate output. The style sheets - will then include or exclude the marked text, according to the conditions. - Profiling allows you to keep both common and product-specific content in - one XML file and select at production time which information to include in - the output. - If you need to use profiling in your writing, adhere to the following guidelines: - - - - Identify different variants that you want to apply to the general piece of text - and assign clear and short identifiers to them, sticking to lowercase. - These identifiers act as aliases for longer products or - deliverables. - If you want to apply more than one identifier to an element, separate them - with a semicolon. - - - - - Select one or more profiling attributes and add them to the text snippets that - are conditional. The tagged snippets will only be included in the output if - all required conditions are fulfilled. In most cases, the attribute to use is - os. For different processor architectures, use - arch. The general-purpose attribute is condition. - - - - Mark the variants in your text with the relevant identifiers. Any content that - is valid for all conditions does not need any profiling attributes. The - respective content will always be included in the output formats generated - from the XML sources. - - - - Create a different DC file for each variant. Add the respective profiling - variable and its value to the DC file. - - - - DocBook allows you to use multiple profiling attributes to handle more - complex scenarios. For example, if you have conditions for architecture - (arch) and operating system (os), - you can create different versions of a document for different combinations - of these conditions, as shown in . - - - - Single profiling with the attribute <tag class="attribute">os</tag> - +
+
+ Profiling + + Profiling is convenient for the creation of consistent documentation + across different products or product lines. This is especially beneficial + when similar products share a considerable amount of features, with only + a few differences. Instead of maintaining separate documentation for each + product, you can share most of the XML source code and only vary text + snippets where necessary. In DocBook XML files, you can mark some + elements as conditional by using profiling attributes. Specify which + conditions apply to the output when processing the files to generate + output. The style sheets will then include or exclude the marked text, + according to the conditions. + + + Profiling allows you to keep both common and product-specific content in + one XML file and select at production time which information to include + in the output. + + + If you need to use profiling in your writing, adhere to the following + guidelines: + + + + + Identify different variants that you want to apply to the general + piece of text and assign clear and short identifiers to them, + sticking to lowercase. These identifiers act as + aliases for longer products or deliverables. If you + want to apply more than one identifier to an element, separate them + with a semicolon. + + + + + Select one or more profiling attributes and add them to the text + snippets that are conditional. The tagged snippets will only be + included in the output if all required conditions are fulfilled. In + most cases, the attribute to use is os. For + different processor architectures, use arch. The + general-purpose attribute is condition. + + + + + Mark the variants in your text with the relevant identifiers. Any + content that is valid for all conditions does not need any profiling + attributes. The respective content will always be included in the + output formats generated from the XML sources. + + + + + Create a different DC file for each variant. Add the respective + profiling variable and its value to the DC file. + + + + + DocBook allows you to use multiple profiling attributes to handle + more complex scenarios. For example, if you have conditions for + architecture (arch) and operating system + (os), you can create different versions of a + document for different combinations of these conditions, as shown in + . + + + + + Single profiling with the attribute <tag class="attribute">os</tag> + <?xml version="1.0" encoding="UTF-8"?> [...] <phrase os="sles;sled">Note that the official update repository is only available after registering your SUSE Linux Enterprise Server installation.</phrase> - - - - DC file with profiling for SLES - + + + DC file with profiling for SLES + MAIN="MAIN.SLEDS.xml" ROOTID=book-administration ## Profiling PROFOS="sles" ... - - - - Multiple profiling with attributes <tag class="attribute">os</tag> and <tag class="attribute">arch</tag> - + + + Multiple profiling with attributes <tag class="attribute">os</tag> and <tag class="attribute">arch</tag> + <?xml version="1.0" encoding="UTF-8"?> [...] Entire hard disks are listed as devices without numbers, such as <filename>/dev/sda</filename><phrase arch="zseries;aarch64" os="sles;sled;slemicro"></phrase>. - - -
- -
- Questions and answers - - Use questions-and-answers sections to present information about - troubleshooting or commonly asked questions about a product. Never use - questions-and-answers sections to explain trivia, such as how a product - got its name. Keep your audience in mind. See also - . - - - Questions must always end in a ?. Where explanations - longer than three paragraphs are necessary for an answer, add a cross-reference - to an explanation outside of the questions-and-answers section. - See also . - - - When a questions-and-answers section contains over 10 questions and there - are clear topical divisions, add - qandadiv - elements to further structure the section. - - - Example of a questions-and-answers section (source) + +
+
+ Questions and answers + + Use questions-and-answers sections to present information about + troubleshooting or commonly asked questions about a product. Never use + questions-and-answers sections to explain trivia, such as how a product + got its name. Keep your audience in mind. See also + . + + + Questions must always end in a ?. Where explanations + longer than three paragraphs are necessary for an answer, add a + cross-reference to an explanation outside of the questions-and-answers + section. See also . + + + When a questions-and-answers section contains over 10 questions and there + are clear topical divisions, add qandadiv + elements to further structure the section. + + + Example of a questions-and-answers section (source) <qandaset> <title>Example of a questions-and-answers section</title> <qandaentry> @@ -2696,280 +2623,293 @@ Entire hard disks are listed as devices without numbers, such as </answer> </qandaentry> </qandaset> - - - Example of a questions-and-answers section (output) - - - - How can I check if the product was correctly installed? - - - - - Open the log file. Look for entries starting with - Failed. - - - - - - - Why does the error Not enough disk space occur - during installation? - - - - - There are less than 4 GB of space available on the selected partition. - - - - - - Elements related to - <tag class="emptytag">qandaset</tag> - - - - Element - Web link - - - - - - - <tag class="emptytag">qandaset</tag> - - Block element containing a - title - (optional) and multiple - qandaentry - or - qandadiv - elements. - - - - - - - - - - <tag class="emptytag">qandadiv</tag> - - Block element containing a - title - and multiple - qandaentry - elements. Used to structure a - qandaset - into smaller topical subsections. - - - - - - - - - - <tag class="emptytag">qandaentry</tag> - - Block element used to associate a - question - with an - answer. - - - - - - - - - - <tag class="emptytag">question</tag> - - Block element containing the question. Use a single - para - element inside. - - - - - - - - - - <tag class="emptytag">answer</tag> - - Block element containing the answer. Use - para - elements inside. - - - - - - - - -
-
- -
- References to other external resources - sknorr, 2014-01-22: This section could probably use a better + + + Example of a questions-and-answers section (output) + + + + How can I check if the product was correctly installed? + + + + + Open the log file. Look for entries starting with + Failed. + + + + + + + Why does the error Not enough disk space occur + during installation? + + + + + There are less than 4 GB of space available on the selected + partition. + + + + + + Elements related to <tag class="emptytag">qandaset</tag> + + + + Element + Web link + + + + + + + <tag class="emptytag">qandaset</tag> + + Block element containing a title + (optional) and multiple + qandaentry or + qandadiv elements. + + + + + + + + + + <tag class="emptytag">qandadiv</tag> + + Block element containing a title + and multiple qandaentry elements. + Used to structure a qandaset into + smaller topical subsections. + + + + + + + + + + <tag class="emptytag">qandaentry</tag> + + Block element used to associate a + question with an + answer. + + + + + + + + + + <tag class="emptytag">question</tag> + + Block element containing the question. Use a single + para element inside. + + + + + + + + + + <tag class="emptytag">answer</tag> + + Block element containing the answer. Use + para elements inside. + + + + + + + + +
+
+
+ References to other external resources + sknorr, 2014-01-22: This section could probably use a better structure instead of this mishmash. - - To reference file names, use the - filename - element. To reference e-mail addresses, use the - email - element. In either case, do not include a protocol prefix, that is - file:// or mailto:, respectively. - See also . - - - Reference man pages and info pages in this format: - - - - the man page of command + To reference file names, use the filename + element. To reference e-mail addresses, use the + email element. In either case, do not include + a protocol prefix, that is file:// or + mailto:, respectively. See also + . - - - the info page of command + Reference man pages and info pages in this format: + + + + + the man page of command + + + + + the info page of command + + + + + In a situation where the category of the page is needed, append the + category in parentheses. For example, use (man 9 + command). - - - - In a situation where the category of the page is needed, append the - category in parentheses. For example, use (man 9 - command). - To learn more about subcommands, see the man page of <command>command</command>. - - Insert references to external (non-&suse;) physical books in the format - Title by Author (ISBN #00000000). Inclusion of the ISBN is - optional. Place the title in a - citetitle - element. For example: - + + Insert references to external (non-&suse;) physical books in the format + Title by Author (ISBN #00000000). Inclusion of the ISBN is + optional. Place the title in a citetitle + element. For example: + <citetitle>Lorem Ipsum</citetitle> by Dolores S. Amet (ISBN 0-246-52044-7) is a useful guide. -Note that citetitle is not translated. - - As an author, where possible, provide language-specific references to - translators in XML comments (see also ). - As a translator, look for corresponding language-specific resources where - none have been provided. For URLs, provide only the language-specific - version of a site. Use the English version as a fallback. - For books, provide the - title of the translated version along with the original title if such a - translation exists. - - - Other types of references to resources are described in - and . - -
- -
- Tables - - Use tables to present many similar facts. Tables are easy to - scan and compare. Always keep tables simple enough to not require long - explanations even for readers unfamiliar with the topic. - - - A table always has a title and should have an - xml:id - attribute. - - - Typical use cases of tables include: - - - Lookup tables for specific information - - Whenever users need to check for data that applies to them, - create lookup tables. For example, use a table to sum up system requirements. - - - - Matrix tables - - Whenever users need to quickly check whether a specific combination - of options works or not. For example, use a matrix table to visualize supported - combinations or update options. - - - - - As there are use cases for tables, there are cases when not - to use tables: - - - - Value and description pairs are better handled by means of a descriptive list. - - - Wordy explanations or descriptions should not be used in tables. - - - Complex layout constructs (screens, code) should not be used in tables. - - - - Some general style tips for tables: - - - Structure the table to have more rows than columns - - Readers prefer to skim for information that is aligned vertically. When designing - tables, consider swapping rows and columns to provide a consistent - user experience. - - - Narrow down columns - - Compress the data in your table as much as you possibly can. Table - cells with less content are more easily parsed by readers. Consider using - icons, adding repeating words into column titles, or using shorter number - formats. - - - Use colors to lead the reader's eyes - - Use colors to make the information stand out. If you just want to - highlight small bits, use bright colors. If you need to color entire cells, - use pastels. This option should only be used with matrix type tables. - - - - Use striped rows - - Color every second row in light gray to make sure readers do not - accidentally slip between lines. This should be the default for long - tables. Do not use striped rows in matrix type tables with additional cell background coloring. - You may also consider disabling striped rows for short tables to not confuse readers. - - - - - - - - Example of a table (source) + + Note that citetitle is not translated. + + + As an author, where possible, provide language-specific references to + translators in XML comments (see also ). + As a translator, look for corresponding language-specific resources where + none have been provided. For URLs, provide only the language-specific + version of a site. Use the English version as a fallback. For books, + provide the title of the translated version along with the original title + if such a translation exists. + + + Other types of references to resources are described in + and . + +
+
+ Tables + + Use tables to present many similar facts. Tables are easy to scan and + compare. Always keep tables simple enough to not require long + explanations even for readers unfamiliar with the topic. + + + A table always has a title and should have an + xml:id attribute. + + + Typical use cases of tables include: + + + + Lookup tables for specific information + + + Whenever users need to check for data that applies to them, create + lookup tables. For example, use a table to sum up system + requirements. + + + + + Matrix tables + + + Whenever users need to quickly check whether a specific combination + of options works or not. For example, use a matrix table to + visualize supported combinations or update options. + + + + + + As there are use cases for tables, there are cases when + not to use tables: + + + + + Value and description pairs are better handled by means of a + descriptive list. + + + + + Wordy explanations or descriptions should not be used in tables. + + + + + Complex layout constructs (screens, code) should not be used in + tables. + + + + + Some general style tips for tables: + + + + Structure the table to have more rows than columns + + + Readers prefer to skim for information that is aligned vertically. + When designing tables, consider swapping rows and columns to + provide a consistent user experience. + + + + + Narrow down columns + + + Compress the data in your table as much as you possibly can. Table + cells with less content are more easily parsed by readers. Consider + using icons, adding repeating words into column titles, or using + shorter number formats. + + + + + Use colors to lead the reader's eyes + + + Use colors to make the information stand out. If you just want to + highlight small bits, use bright colors. If you need to color + entire cells, use pastels. This option should only be used with + matrix type tables. + + + + + + Use striped rows + + + Color every second row in light gray to make sure readers do not + accidentally slip between lines. This should be the default for + long tables. Do not use striped rows in matrix type tables with + additional cell background coloring. You may also consider + disabling striped rows for short tables to not confuse readers. + + + + + + + Example of a table (source) <informaltable> <tgroup cols="2"> <thead> @@ -2990,225 +2930,210 @@ Entire hard disks are listed as devices without numbers, such as </tbody> </tgroup> </informaltable> - - - Example of a table (output) - - - - - File System - Maximum File Size - - - - - Ext2 (1 kB block size) - 16 GB - - - Ext2 (2 kB block size) - 256 GB - - - - - - - - - - Elements related to - <tag class="emptytag">table</tag> - - - - Element - Web link - - - - - - - <tag class="emptytag">table</tag> - - Formal block element that contains a - title - and a - tgroup - element. - - - - - - - - - - <tag class="emptytag">informaltable</tag> - - Informal block element that contains a - tgroup - element. - - - - - - - - - - <tag class="emptytag">tgroup</tag> - - Wrapper for the content of a table. Can contain one or more - colspec - and one - thead. Contains a - tbody - - - - - - - - - - <tag class="emptytag">colspec</tag> - - Element to define common properties for a column. - - - - - - - - - - <tag class="emptytag">thead</tag> - - Element to mark up a table head. Contains a - row - element. - - - - - - - - - - <tag class="emptytag">tbody</tag> - - Element to mark up the table body. Contains multiple - row - elements. - - - - - - - - - - <tag class="emptytag">row</tag> - - Element to mark up a table row. Contains multiple - entry - elements. - - - - - - - - - - <tag class="emptytag">entry</tag> - - Element to mark up a table cell. - - - - - - - - -
-
- -
- User interface items - - To mark up single user interface items, use - guimenu. To mark up nested menu structures, use - menuchoice - as a wrapper for multiple - guimenu - elements. Separators between - guimenu - elements are then created automatically. - - - For more information about language aspects, see - . - - - Example of a single user interface item + + + Example of a table (output) + + + + + File System + Maximum File Size + + + + + Ext2 (1 kB block size) + 16 GB + + + Ext2 (2 kB block size) + 256 GB + + + + + + + Elements related to <tag class="emptytag">table</tag> + + + + Element + Web link + + + + + + + <tag class="emptytag">table</tag> + + Formal block element that contains a + title and a + tgroup element. + + + + + + + + + + <tag class="emptytag">informaltable</tag> + + Informal block element that contains a + tgroup element. + + + + + + + + + + <tag class="emptytag">tgroup</tag> + + Wrapper for the content of a table. Can contain one or more + colspec and one + thead. Contains a + tbody + + + + + + + + + + <tag class="emptytag">colspec</tag> + + Element to define common properties for a column. + + + + + + + + + + <tag class="emptytag">thead</tag> + + Element to mark up a table head. Contains a + row element. + + + + + + + + + + <tag class="emptytag">tbody</tag> + + Element to mark up the table body. Contains multiple + row elements. + + + + + + + + + + <tag class="emptytag">row</tag> + + Element to mark up a table row. Contains multiple + entry elements. + + + + + + + + + + <tag class="emptytag">entry</tag> + + Element to mark up a table cell. + + + + + + + + +
+
+
+ User interface items + + To mark up single user interface items, use + guimenu. To mark up nested menu structures, + use menuchoice as a wrapper for multiple + guimenu elements. Separators between + guimenu elements are then created + automatically. + + + For more information about language aspects, see + . + + + Example of a single user interface item To open a file, click <guimenu>Open</guimenu>. - - - Example of nested user interface items + + + Example of nested user interface items To save a file, use <menuchoice><guimenu>File</guimenu><guimenu>Save</guimenu></menuchoice>. - - - Elements related to - <tag class="emptytag">guimenu</tag> - - - - Element - Web link - - - - - - - <tag class="emptytag">menuchoice</tag> - - Inline element containing multiple - guimenu - elements that together form a nested menu structure. - - - - - - - - - - <tag class="emptytag">guimenu</tag> - - Inline element to mark up a single user interface item. - - - - - - - - -
-
+ + + Elements related to <tag class="emptytag">guimenu</tag> + + + + Element + Web link + + + + + + + <tag class="emptytag">menuchoice</tag> + + Inline element containing multiple + guimenu elements that together + form a nested menu structure. + + + + + + + + + + <tag class="emptytag">guimenu</tag> + + Inline element to mark up a single user interface item. + + + + + + + + +
+
diff --git a/xml/docu_styleguide.taglist.xml b/xml/docu_styleguide.taglist.xml index 1f1586ec..2653ec03 100644 --- a/xml/docu_styleguide.taglist.xml +++ b/xml/docu_styleguide.taglist.xml @@ -9,123 +9,118 @@ xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xlink="http://www.w3.org/1999/xlink" > - - DocBook tags - - - The &suse; and openSUSE user documentation is written with DocBook and uses a - Relax NG schema that defines a restricted set of DocBook tags. - - - The following tables list and describe all DocBook tags used for writing - most of the &suse; user documentation. They also show which tags are - translated and which tags will be blocked for translation, which means that - those tags stay in English. - The tables are divided into four categories, listing the elements of each - respective category. - - - With GeekoDoc 2, it is also possible to use the Internationalization Tag Set - (ITS) to explicitly indicate whether a tag should be translated or not. - For more information on ITS tags, see . - - - For more information on GeekoDoc, see - - - - For more information on all tags available in DocBook, see - - - -
- Using DocBook tags - -
- Meta elements + DocBook tags - All the elements at the section level and above, and many other elements, - include a wrapper for meta information about the content. - The meta information wrapper is designed to contain bibliographic - information about the content (author, title, publisher, etc.) as well - as other meta information such as revision histories, keyword sets and - index terms. + The &suse; and openSUSE user documentation is written with DocBook and uses + a Relax NG schema that defines a restricted set of DocBook tags. - - - - - - - - Element name - Description - Translation - - - - - - + + The following tables list and describe all DocBook tags used for writing + most of the &suse; user documentation. They also show which tags are + translated and which tags will be blocked for translation, which means that + those tags stay in English. The tables are divided into four categories, + listing the elements of each respective category. + + + With GeekoDoc 2, it is also possible to use the Internationalization Tag + Set (ITS) to explicitly indicate whether a tag should be translated or not. + For more information on ITS tags, see . + + + For more information on GeekoDoc, see + + + + For more information on all tags available in DocBook, see + + +
+ Using DocBook tags +
+ Meta elements + + All the elements at the section level and above, and many other + elements, include a wrapper for meta information about the content. The + meta information wrapper is designed to contain bibliographic + information about the content (author, title, publisher, etc.) as well + as other meta information such as revision histories, keyword sets and + index terms. + + + + + + + + + Element name + Description + Translation + + + + + + abstract - - + + Use an abstract to summarize the information provided in a book, article, or set in five or fewer sentences. - + Yes - - - - + + + + author personame firstname surname - - + + Name of an individual author - No - - - - + No + + + + authorgroup author personame firstname surname - - + + Wrapper for author information when a document has multiple authors or collaborators - + No - - - - + + + + date - - + + Date of publication or revision of a document - + No - - - - + + + + info dm:docmanager dm:bugtracker @@ -137,569 +132,616 @@ info dm:translation dm:editurl - - - info: Wrapper to contain bibliographic + + info: Wrapper to contain bibliographic information about the content and other meta info. dm:PLACEHOLDER: SUSE-specific info needed by the doc-manager tool and DAPS to process and build &suse; user documentation. - + No - - - - + + + + indexterm primary secondary - - + + To create an index - - - Yes - - - Legacy element, do not use for new documentation - - - - - - 2022-03-28: jufa: check if still in use or needed for SEO + + + Yes + + + Legacy element, do not use for new documentation + + + + + + 2022-03-28: jufa: check if still in use or needed for SEO purposes - + keywordset keyword - - + + A set of keywords describing the content of a document - - No - For TM parser settings, set to Yes. - - - - - + + + No + + + For TM parser settings, set to Yes. + + + + + + legalnotice - - - Yes - - - - + + + Yes + + + + productname - - + + The formal name of a product - No - - - - + No + + + + productnumber - - + + A number assigned to a product - No - - - - + No + + + + remark - - + + A remark (or comment) intended for presentation in a draft manuscript - No - - - - + No + + + + subtitle - - + + The subtitle of a document. Often used for &suse; Best Practices guides - Yes - - - - + Yes + + + + title - - - - The text of the title for a section of a document or for a formal - block-level element - - - For document titles, such as book, article and set titles, use - title-style capitalization. Apply sentence-style capitalization to all - running text and all types of headings and titles that are part of the - document content. - - - Yes - - - - + + + + The text of the title for a section of a document or for a + formal block-level element + + + For document titles, such as book, article and set titles, + use title-style capitalization. Apply sentence-style + capitalization to all running text and all types of headings + and titles that are part of the document content. + + + Yes + + + + titleabbrev - - + + The abbreviation of a title. For example, it can be used to show shorter titles in the table of contents. - Yes - - - - -
- -
- Structure elements - - - Structure elements are needed for sectioning and structuring your document, - such as defining chapters, appendix, etc. - - - Most structure elements do not need translations. The child elements like - title are translated. - - - - - - - - - - Element name - Description - Translation - - - - - - + Yes + + + + +
+
+ Structure elements + + + Structure elements are needed for sectioning and structuring your + document, such as defining chapters, appendix, etc. + + + Most structure elements do not need translations. The child elements + like title are translated. + + + + + + + + + + Element name + Description + Translation + + + + + + article - - An article - Yes - - - - + + An article + Yes + + + + appendix - - An appendix in a book or article - - No - For TM parser settings, set to Yes. - - - - - + + An appendix in a book or article + + + No + + + For TM parser settings, set to Yes. + + + + + + bridgehead - - - A free-floating heading. - Use sparingly and work with sections instead. - - Yes - - - - + + + + A free-floating heading. + + + Use sparingly and work with sections instead. + + + Yes + + + + book - - A book - - No - For TM parser settings, set to Yes. - - - - - + + A book + + + No + + + For TM parser settings, set to Yes. + + + + + + chapter - - A chapter, as of a book - - No - For TM parser settings, set to Yes. - - - - - + + A chapter, as of a book + + + No + + + For TM parser settings, set to Yes. + + + + + + formalpara - - A paragraph with the title rendered as a run-in head. - Use to create more compact lists, for example: - - <command>who</command> - - Lists currently logged in users. - - - - <command>w</command> - - Shows who is logged in and what they are doing. - - - - Yes - - - - + + + + A paragraph with the title rendered as a run-in head. Use to + create more compact lists, for example: + + + <command>who</command> + + Lists currently logged in users. + + + + <command>w</command> + + Shows who is logged in and what they are doing. + + + + Yes + + + + section - - A recursive section, unnumbered - - No - For TM parser settings, set to Yes. - - - - - + + A recursive section, unnumbered + + + No + + + For TM parser settings, set to Yes. + + + + + + sect1 sect2 sect3 ... - - Numbered sections that must be properly nested - - No - For TM parser settings, set to Yes. - - - - - + + Numbered sections that must be properly nested + + + No + + + For TM parser settings, set to Yes. + + + + + + set - - A collection of books - Yes - - - - + + A collection of books + Yes + + + + para - - A paragraph - Yes - - - - + + A paragraph + Yes + + + + part - - A division in a book - - No - For TM parser settings, set to Yes. - - - - - + + A division in a book + + + No + + + For TM parser settings, set to Yes. + + + + + + preface - - Introductory matter preceding the first chapter of a book - - No - For TM parser settings, set to Yes. - - - - - + + Introductory matter preceding the first chapter of a book + + + No + + + For TM parser settings, set to Yes. + + + + + + qandaset qandaentry question answer - - Used for FAQs - Yes - - - - -
- -
- Block elements - - The block elements occur immediately below the component and sectioning - elements. These are the (roughly) paragraph-level elements in DocBook. - They can be divided into a number of categories: lists, admonitions, - line-specific environments, synopses of several sorts, tables, figures, - examples, and a dozen or more miscellaneous elements. - - - - - - - - - Element name - Description - Translation - - - - - - + + Used for FAQs + Yes + + + + +
+
+ Block elements + + The block elements occur immediately below the component and sectioning + elements. These are the (roughly) paragraph-level elements in DocBook. + They can be divided into a number of categories: lists, admonitions, + line-specific environments, synopses of several sorts, tables, figures, + examples, and a dozen or more miscellaneous elements. + + + + + + + + + Element name + Description + Translation + + + + + + calloutlist callout para - - + + List of callouts and their descriptions. A called out description of a marked area. - - No - For TM parser settings, set to Yes. - - Child element para is translated. - - - - - - + + + No + + + For TM parser settings, set to Yes. + + + Child element para is translated. + + + + + + example - - An example - Yes - - - - + + An example + Yes + + + + figure title mediaobject imageobject imagedata - - Figure with title - - No - For TM parser settings, set to Yes. - - Child element title is translated. - - - - - - + + Figure with title + + + No + + + For TM parser settings, set to Yes. + + + Child element title is + translated. + + + + + + glossary glossdef glossdiv glossentry glossterm - - A glossary - Yes - - - - + + A glossary + Yes + + + + important tittle - - + + Use this elements to give vital information. - Yes - - - - + Yes + + + + informalfigure - - Figure without a title - No - - - - + + Figure without a title + No + + + + informaltable - - + + Table without a title - Yes - - - - + Yes + + + + itemizedlist listitem - - + + Unordered, bulleted list - Yes - - - - + Yes + + + + note title para - - - - A message set off from the text. - - - Use this element to highlight software version differences. - - - + + + + A message set off from the text. + + + Use this element to highlight software version differences. + + + Yes - - - - + + + + orderedlist listitem - - + + Numbered list with attributes to control the type of enumeration - Yes - - - - + Yes + + + + procedure step substeps stepalternatives - - - - procedure: A list of operations to be - performed in a well-defined sequence - - - step: A unit of action in a procedure - - - Yes - - - - + + + + procedure: A list of operations + to be performed in a well-defined sequence + + + step: A unit of action in a + procedure + + + Yes + + + + programlisting - - - - A literal listing of a program or a part of a program. Use for - program source or source fragment listings. Formatted as a displayed - block. Similar to screen. - - - No - - - - + + + + A literal listing of a program or a part of a program. Use + for program source or source fragment listings. Formatted as + a displayed block. Similar to + screen. + + + No + + + + qandset qandaentry question answer - - + + List of questions and answers, used for FAQs - Yes - - - - + Yes + + + + screen - - + + Text that a user sees on a computer screen - No - - - - + No + + + + simplelist member - - + + Undecorated list of single words or short phrases - Yes - - - - + Yes + + + + table title tgroup @@ -711,524 +753,537 @@ table row entry - - + + Formal table with title - - - No - - For TM parser settings, set to Yes. - - Except for child elements title and - entry - - - - - - + + + No + + + For TM parser settings, set to Yes. + + + Except for child elements title + and entry + + + + + + textobject - - Explanatory text for images to aid visually impaired users and show + + Explanatory text for images to aid visually impaired users and show when the image cannot be loaded because of an error - Yes - - - - + Yes + + + + tip title para - - To introduce guidelines or give tips - Yes - - - - + + To introduce guidelines or give tips + Yes + + + + variablelist varlistentry term - - List of terms and definitions or descriptions - Yes - - - - + + List of terms and definitions or descriptions + Yes + + + + warning title para - - + + To warn of security issues, potential loss of data, damage to hardware, or physical hazards. Warnings must always precede the action to which they apply. - Yes - - - - -
- -
- Inline elements - - Inline elements are used to mark up running text. In published documents, - inline elements often cause a font change or other small change, but they - do not cause line or paragraph breaks. - - - - - - - - - Element name - Description - Translation - - - - - - + Yes + + + + +
+
+ Inline elements + + Inline elements are used to mark up running text. In published + documents, inline elements often cause a font change or other small + change, but they do not cause line or paragraph breaks. + + + + + + + + + Element name + Description + Translation + + + + + + citetitle - - + + To reference names of printed books. To refer to any of our guides, use xref or link. - No - - - - + No + + + + co - - + + Part of calloutlist. The location of a callout embedded in text. - No - - - - + No + + + + code - - An inline code fragment - No - - - - + + An inline code fragment + No + + + + command - - A software command - No - - - - + + A software command + No + + + + constant - - A programming or system constant - No - - - - + + A programming or system constant + No + + + + email - - An e-mail address - No - - - - + + An e-mail address + No + + + + emphasis - - Emphasized text - Yes - - - - + + Emphasized text + Yes + + + + envar - - A software environment variable - No - - - - + + A software environment variable + No + + + + filename - - + + Name of a file or path as well as directories, printers or flash drives - No - - - - + No + + + + function - - + + Name of a function or subroutine, as in a programming language - No - - - - + No + + + + guimenu - - + + To mark up all GUI elements like button, label and menu - - Yes - - Depends on whether UI is translated or not. If not, use ITS tag. - - - - - - + + + Yes + + + Depends on whether UI is translated or not. If not, use ITS + tag. + + + + + + indexterm primary secondary - - + + Index marker - - - Yes - - - Legacy element, do not use for new documentation - - - - - - + + + Yes + + + Legacy element, do not use for new documentation + + + + + + inlinemediaobject - - + + An inline media object (video, audio, image...) - No - - - - + No + + + + keycap - - - The text printed on a key on a keyboard - - For function keys, always use with function, for example: - <keycap function="control"></keycap> - - - Yes - - - - + + + + The text printed on a key on a keyboard + + + For function keys, always use with function, for example: + <keycap function="control"></keycap> + + + Yes + + + + keycombo keycap - - + + A combination of input actions on a keyboard - Yes - - - - + Yes + + + + link - - + + A hypertext link. Use the secure protocol prefix (https://), if possible. - No - - - - + No + + + + literal - - + + To mark up data taken literally from a computer system - No - - - - + No + + + + menuchoice - - + + A selection or series of selections from a menu - Yes - - - - + Yes + + + + option - - + + An option for a software command - No - - - - + No + + + + package - - + + Name of a software or application package. Replaces systemitem class="resource". - No - - - - + No + + + + parameter - - + + A value or a symbolic reference to a value - No - - - - + No + + + + phrase - - + + A span of text - Yes - - - - + Yes + + + + productname - - - - The formal name of a product - - - No - - - - + + + + The formal name of a product + + + No + + + + prompt - - + + A character or string indicating the start of an input field in a computer display - No - - - - + No + + + + quote - - + + To quote from sources, such as books. In all other cases, do not use quotation marks. - Yes - - - - + Yes + + + + replaceable - - + + Content that may or must be replaced by the user. Capitalize placeholder text in all contexts where this is not detrimental to content intelligibility. Do not use spaces within placeholders, use underscores instead. - No - - - - + No + + + + systemitem - - + + A system-related item or term - No - - - - + No + + + + subscript - - - A subscript. For example: - H2O - - Yes - - - - + + + + A subscript. For example: + + + H2O + + + Yes + + + + superscript - - - A superscript. For example: - X2 - - Yes - - - - + + + + A superscript. For example: + + + X2 + + + Yes + + + + tag - - + + A component of XML (or SGML) markup - No - - - - + No + + + + trademark - - + + To mark a trademark with TM - - No - - - - + + No + + + + uri - - + + For links that should not be clickable - No - - - - + No + + + + varname - - + + The name of a variable - No - - - - + No + + + + xi:include - - + + To construct documents from different files - No - - - - + No + + + + xref - - + + A cross-reference to another part of the document - No - - - - -
-
- -
- Using ITS tags - - With GeekoDoc 2, it is possible to use the Internationalization Tag Set (ITS) - tags to explicitly indicate that a tag should be translated or not. - - - For this, you need to have the ITS namespace enabled in the XML file. Make - sure the following line is added to the root element: - xmlns:its="http://www.w3.org/2005/11/its". - - - For example: - You have used the tag guimenu which is usually - translated but in this particular case it should not be translated. - - - To mark the tag correctly, use the ITS tag as shown here: - - + No + + + + +
+
+
+ Using ITS tags + + With GeekoDoc 2, it is possible to use the Internationalization Tag Set + (ITS) tags to explicitly indicate that a tag should be translated or not. + + + For this, you need to have the ITS namespace enabled in the XML file. + Make sure the following line is added to the root element: + xmlns:its="http://www.w3.org/2005/11/its". + + + For example: You have used the tag guimenu + which is usually translated but in this particular case it should not be + translated. + + + To mark the tag correctly, use the ITS tag as shown here: + + Click <guimenu its:translate="no">Save</guimenu>. -
+
diff --git a/xml/docu_styleguide.techwriting.xml b/xml/docu_styleguide.techwriting.xml index a28332bc..e54fba7a 100644 --- a/xml/docu_styleguide.techwriting.xml +++ b/xml/docu_styleguide.techwriting.xml @@ -5,72 +5,71 @@ %entities; ]> - Writing technical documentation - - - Technical writing has certain characteristics that make it different from - other types of writing. Its objective is to provide readers with complex - information and comprehensive answers they are searching for. The content - should be well-structured, clear and concise. Effective technical - documentation is straightforward, detailed and focused on problem-solving, - and there is a specific workflow for its creation: - - - - - Defining the target audience - - - Adjust tone, style and technicality of the text based on the intended - audience. Keep in mind that not all facts that seem obvious to you will be - obvious to your readers. - - - - - Researching a topic - - - Start with research on the information that is relevant to the target - audience. Receive essential input from issue tracking systems like GitHub, - and project management tools. - - - - - Writing about a topic - - - Start writing at an early stage, even if you have not finished your - research yet. Prepare a draft document and discuss it with subject-matter - experts. - - - - - Getting reviews - - - In a first review of your text, identify and fix the most obvious issues - like typos, unfinished sentences, etc. After self-review, ask for a - technical review by dedicated specialists. A technical review uncovers - technical or factual errors like missing or misspelled package names, - wrong commands or forgotten options. - - - Request a peer review which can improve your text and detect any - structural problems or logical traps. You can then do a spell check, link - check and style check with the DAPS tool. - - - Finally, ask for a linguistic review that tackles language issues, typos, - inconsistencies, and style guide compliance. - - - - - - For more information on how to produce meaningful content that will rank high - on the Web, see and . - - + Writing technical documentation + + Technical writing has certain characteristics that make it different from + other types of writing. Its objective is to provide readers with complex + information and comprehensive answers they are searching for. The content + should be well-structured, clear and concise. Effective technical + documentation is straightforward, detailed and focused on problem-solving, + and there is a specific workflow for its creation: + + + + Defining the target audience + + + Adjust tone, style and technicality of the text based on the intended + audience. Keep in mind that not all facts that seem obvious to you + will be obvious to your readers. + + + + + Researching a topic + + + Start with research on the information that is relevant to the target + audience. Receive essential input from issue tracking systems like + GitHub, and project management tools. + + + + + Writing about a topic + + + Start writing at an early stage, even if you have not finished your + research yet. Prepare a draft document and discuss it with + subject-matter experts. + + + + + Getting reviews + + + In a first review of your text, identify and fix the most obvious + issues like typos, unfinished sentences, etc. After self-review, ask + for a technical review by dedicated specialists. A technical review + uncovers technical or factual errors like missing or misspelled + package names, wrong commands or forgotten options. + + + Request a peer review which can improve your text and detect any + structural problems or logical traps. You can then do a spell check, + link check and style check with the DAPS tool. + + + Finally, ask for a linguistic review that tackles language issues, + typos, inconsistencies, and style guide compliance. + + + + + + For more information on how to produce meaningful content that will rank + high on the Web, see and + . + + diff --git a/xml/docu_styleguide.terminology.xml b/xml/docu_styleguide.terminology.xml index 940f5da8..d63e8c6c 100644 --- a/xml/docu_styleguide.terminology.xml +++ b/xml/docu_styleguide.terminology.xml @@ -5,2381 +5,2392 @@ %entities; ]> - Terminology and general vocabulary - - - The following two tables define technical terms and general vocabulary for - use in SUSE documentation. See also . - - - If unable to find a term below, check &suse;'s official terminology database, - TermWeb. It contains - company-specific terminology in English and all our supported languages. TermWeb - can be accessed only by &suse; employees and external partners with a SUSE account - (get one at ). - - - Terminology - - The following table defines the correct spellings and denominations for - technical terms in SUSE documentation. Always use the entry listed under - Accepted in the table below. All terms are reproduced in - sentence-style capitalization. + Terminology and general vocabulary + + + The following two tables define technical terms and general vocabulary for + use in SUSE documentation. See also . + + + If unable to find a term below, check &suse;'s official terminology + database, TermWeb. It + contains company-specific terminology in English and all our supported + languages. TermWeb can be accessed only by &suse; employees and external + partners with a SUSE account (get one at + ). + + Terminology - - - - - Accepted - Rejected [Reason] - Part of Speech; Usage Guideline/Definition - - - - - - 32-bit - 32 Bit, 32 bit, 32-Bit, 32Bit, 32bit - adjective - - - 3D - 3 D, 3 d, 3.D., 3.d., 3-D, 3-d, 3d, Three-D - adjective - - - 64-bit - 64 Bit, 64 bit, 64-Bit, 64Bit, 64bit - adjective - - - AArch64 - ARM64, ARMv8 - noun; processor architecture - - - - (to) activate sth. - (to) block sth., (to) check sth., (to) choose sth., + + The following table defines the correct spellings and denominations for + technical terms in SUSE documentation. Always use the entry listed under + Accepted in the table below. All terms are reproduced in + sentence-style capitalization. + + + + + + + Accepted + Rejected [Reason] + Part of Speech; Usage Guideline/Definition + + + + + + 32-bit + 32 Bit, 32 bit, 32-Bit, 32Bit, 32bit + adjective + + + 3D + 3 D, 3 d, 3.D., 3.d., 3-D, 3-d, 3d, Three-D + adjective + + + 64-bit + 64 Bit, 64 bit, 64-Bit, 64Bit, 64bit + adjective + + + AArch64 + ARM64, ARMv8 + noun; processor architecture + + + + (to) activate sth. + (to) block sth., (to) check sth., (to) choose sth., (to) highlight sth., (to) tick sth. - verb; when referring to check boxes - - - adapter - adaptor - noun - - - add-on - add on, AddOn, addOn, addon - noun - - - address book - addressbook - noun - - - advice - advise [misspelling] - noun - - - (to) advise sth. - (to) advice sth. [misspelling] - verb - - - AMD64/Intel 64 - x64, x86_64, x86-64, 64-bit AMD/Intel, AMD/Intel64 - noun; processor architecture; see also + verb; when referring to check boxes + + + adapter + adaptor + noun + + + add-on + add on, AddOn, addOn, addon + noun + + + address book + addressbook + noun + + + advice + advise [misspelling] + noun + + + (to) advise sth. + (to) advice sth. [misspelling] + verb + + + AMD64/Intel 64 + x64, x86_64, x86-64, 64-bit AMD/Intel, AMD/Intel64 + noun; processor architecture; see also x86 - - - - AOO - Aoo, aoo, OO, oo - noun; when referring to versions 3.4 and after; spelling + + + + AOO + Aoo, aoo, OO, oo + noun; when referring to versions 3.4 and after; spelling according to project standard; acronym of Apache OpenOffice; see also OOo - - - - Apache OpenOffice - Apache Open Office, Apache Openoffice, OpenOffice - noun; when referring to versions 3.4 and after; spelling + + + Apache OpenOffice + Apache Open Office, Apache Openoffice, OpenOffice + + noun; when referring to versions 3.4 and after; spelling according to project standard; acronym is AOO; see also OpenOffice.org - - - - architecture - arch - noun; hardware platform, especially concerning processor + + + + architecture + arch + noun; hardware platform, especially concerning processor platform - - - appendixes - appendices - noun; plural of appendix - - - application - - noun; a computer program designed for a specific task or use - - - audio CD - Audio CD, Audio-CD, CD-Audio, CD Audio, CD audio - - noun - - - back-end - back end, backend - noun - - - (to) back sth. up - (to) backup sth. - verb - - - backup - back-up, back up - noun - - - bare metal - bare-metal, baremetal - noun; a computer without an operating system; also a physical computer (in + + + appendixes + appendices + noun; plural of appendix + + + application + + noun; a computer program designed for a specific task or use + + + audio CD + Audio CD, Audio-CD, CD-Audio, CD Audio, CD audio + + noun + + + back-end + back end, backend + noun + + + (to) back sth. up + (to) backup sth. + verb + + + backup + back-up, back up + noun + + + bare metal + bare-metal, baremetal + noun; a computer without an operating system; also a physical computer (in contrast to a virtualized system) - - - bare-metal - bare metal, baremetal - adjective - - - Bash - BASH, bash - noun; spelling as per the GNU Bash manual - - - Bluetooth - Blue tooth, blue tooth, Blue-tooth, blue-tooth, bluetooth - - noun - - - Bluetooth card - wireless card [card has wires attached to it] - noun; card that enables Bluetooth connections. - - - - boot disk - boot disc [usually a misspelling], boot-disk, bootdisk - noun; disk for starting the system - - - boot loader - boot-loader, bootloader - noun - - - (to) boot using PXE or (to) boot via PXE - - (to) PXE boot - verb - - - Btrfs - B.T.R.F.S., Better FS, BetterFS, Butter FS, ButterFS, + + + bare-metal + bare metal, baremetal + adjective + + + Bash + BASH, bash + noun; spelling as per the GNU Bash manual + + + Bluetooth + Blue tooth, blue tooth, Blue-tooth, blue-tooth, bluetooth + + noun + + + Bluetooth card + wireless card [card has wires attached to it] + noun; card that enables Bluetooth connections. + + + + boot disk + boot disc [usually a misspelling], boot-disk, bootdisk + noun; disk for starting the system + + + boot loader + boot-loader, bootloader + noun + + + (to) boot using PXE or (to) boot via PXE + + (to) PXE boot + verb + + + Btrfs + B.T.R.F.S., Better FS, BetterFS, Butter FS, ButterFS, btrfs - noun; not an acronym + noun; not an acronym sknorr, 2013-09-18: Really, though? Origin is "B-tree File System"? - - - - cursor - pointer [used for pointing device input] - noun; on-screen item indicating the position of keyboard input + + + + cursor + pointer [used for pointing device input] + noun; on-screen item indicating the position of keyboard input focus; see also pointer - - - - CA - C.A., Ca - noun; acronym for + + + + CA + C.A., Ca + noun; acronym for certificate authority - - - - CD - C.D., Cd - noun; acronym for compact disc - - - - CD-ROM - CD ROM, CD-Rom, CD Rom - noun; acronym for + + + + CD + C.D., Cd + noun; acronym for compact disc + + + + CD-ROM + CD ROM, CD-Rom, CD Rom + noun; acronym for compact disc read-only memory - - - - CUPS - C.U.P.S., Cups, cups - noun; spelling as per project standard; acronym for + + + + CUPS + C.U.P.S., Cups, cups + noun; spelling as per project standard; acronym for Common Unix Printing System - - - - case-sensitive - case sensitive, casesensitive - adjective - - - case-insensitive - case insensitive, caseinsensitive - adjective - - - certificate authority - certification authority, + + + + case-sensitive + case sensitive, casesensitive + adjective + + + case-insensitive + case insensitive, caseinsensitive + adjective + + + certificate authority + certification authority, certificating authority, certified authority - noun; acronym is CA - - - - changelog - change log, change-log, ChangeLog - noun; log of changes to software - - - check box - check-box, checkbox, checking option, tick box - noun; avoid, only mention name of option - - - checklist - check list, check-list, ticklist - - noun - - - check mark - check, check-mark, checkmark, tick, tick mark - noun - - - chipset - chip set, chip-set - noun - - - (to) click sth. - (to) click on sth., (to) click onto sth. - verb; using a mouse button, usually to manipulate user interface + noun; acronym is CA + + + + changelog + change log, change-log, ChangeLog + noun; log of changes to software + + + check box + check-box, checkbox, checking option, tick box + noun; avoid, only mention name of option + + + checklist + check list, check-list, ticklist + + noun + + + check mark + check, check-mark, checkmark, tick, tick mark + noun + + + chipset + chip set, chip-set + noun + + + (to) click sth. + (to) click on sth., (to) click onto sth. + verb; using a mouse button, usually to manipulate user interface element; also see press - - - - client/server - client server, client-server, client–server, + + + + client/server + client server, client-server, client–server, client+server - noun/noun - - - (to) close sth. - (to) abort sth. [negative], (to) exit sth., (to) kill sth., + noun/noun + + + (to) close sth. + (to) abort sth. [negative], (to) exit sth., (to) kill sth., (to) terminate sth. - verb; when referring to closing a window; always use + verb; when referring to closing a window; always use quit when ending an application normally; always use terminate when ending an application forcefully - - - codestream - code stream + + + codestream + code stream - noun; stream of code + noun; stream of code - - - (to) coldplug sth. (into sth.) - (to) cold plug sth. (into sth.), (to) cold-plug sth. (into + + + (to) coldplug sth. (into sth.) + (to) cold plug sth. (into sth.), (to) cold-plug sth. (into sth.), (to) coldadd sth., (to) coldswap sth. - verb; adding a component or device to a system while the + verb; adding a component or device to a system while the system is off - - - coldplugging - cold plugging, cold-plugging, coldadding, coldswapping - noun - - - coldpluggable - cold pluggable, cold-pluggable, coldaddable, coldswappable - adjective - - - Common Unix Printing System - Common UNIX Printing System, common Unix printing system - - noun; spelling as per project standard; acronym is + + + coldplugging + cold plugging, cold-plugging, coldadding, coldswapping + noun + + + coldpluggable + cold pluggable, cold-pluggable, coldaddable, coldswappable + adjective + + + Common Unix Printing System + Common UNIX Printing System, common Unix printing system + + noun; spelling as per project standard; acronym is CUPS - - - - command - - noun; a signal that initiates an operation defined by an instruction - - - command line - command-line, commandline - noun - - - command-line - command line, commandline - adjective - - - configuration - config - noun; unless when referring to file extension - - - (to) configure sth. - (to) config sth. - verb - - - (to) connect via SSH (to sth.) - (to) connect by SSH (to sth.), (to) connect over SSH (to sth.), + + + + command + + noun; a signal that initiates an operation defined by an instruction + + + command line + command-line, commandline + noun + + + command-line + command line, commandline + adjective + + + configuration + config + noun; unless when referring to file extension + + + (to) configure sth. + (to) config sth. + verb + + + (to) connect via SSH (to sth.) + (to) connect by SSH (to sth.), (to) connect over SSH (to sth.), (to) connect through SSH (to sth.), (to) connect with SSH (to sth.), (to) SSH (to sth.), (to) ssh (to sth.), (to) ssh in (to sth.), (to) ssh into sth. - verb - - - console - - noun; a physical terminal, used to describe TTYs and PTYs + verb + + + console + + noun; a physical terminal, used to describe TTYs and PTYs and when talking about consoles (e.g. KVM's console); - see also terminal, shell - - - control center - Control Center, Control center, Control-Center, + see also terminal, shell + + + + control center + Control Center, Control center, Control-Center, Control-center, control-center, Controlcenter, controlcenter - noun; generic term, as in: + noun; generic term, as in: the YaST control center or the KDE control center - - - - crash dump - crashdump - noun - - - - (to) create a hard link (to sth.) - (to) hard link (sth.), (to) hardlink (sth.) - verb; see also hard link + + + crash dump + crashdump + + noun - - - (to) create a symbolic link (to sth.) - (to) soft link (sth.), (to) softlink (sth.), + + + (to) create a hard link (to sth.) + (to) hard link (sth.), (to) hardlink (sth.) + verb; see also hard link + + + + (to) create a symbolic link (to sth.) + (to) soft link (sth.), (to) softlink (sth.), (to) symbolic link (sth.), (to) symlink (sth.) - verb; see also hard link - - - - (to) deactivate sth. - (to) deblock sth., (to) uncheck sth., (to) untick sth. - - verb; when referring to check boxes - - - delta RPM - delta-RPM, deltarpm - noun; RPM package that only includes files that changed between + verb; see also hard link + + + + (to) deactivate sth. + (to) deblock sth., (to) uncheck sth., (to) untick sth. + + verb; when referring to check boxes + + + delta RPM + delta-RPM, deltarpm + noun; RPM package that only includes files that changed between a previous and the current version of the package - - - (to) deselect sth. - (to) de-select sth., (to) remove the selection from sth., + + + (to) deselect sth. + (to) de-select sth., (to) remove the selection from sth., (to) un-select sth., (to) unselect sth. - verb; when referring to list entries or text; for check boxes, + verb; when referring to list entries or text; for check boxes, use deactivate - - - - DHCP - D.H.C.P., Dhcp, dhcp - noun - - - dial-up - dial up, dialup - only as an adjective - - - dialog - dialog box, dialog window, dialogue [British], mask [Germanism], + + + + DHCP + D.H.C.P., Dhcp, dhcp + noun + + + dial-up + dial up, dialup + only as an adjective + + + dialog + dialog box, dialog window, dialogue [British], mask [Germanism], screen - noun; a secondary window that gives users progress feedback, + noun; a secondary window that gives users progress feedback, prompts users to perform a command, enter information or select an option - - - directory - dir, folder - noun - - - DNS - D.N.S., DNS name server, Dns, dns - noun; acronym for dynamic name server - - - - (to) double-click sth. - (to) double click sth., (to) double-click on sth., + + + directory + dir, folder + noun + + + DNS + D.N.S., DNS name server, Dns, dns + noun; acronym for dynamic name server + + + + (to) double-click sth. + (to) double click sth., (to) double-click on sth., (to) double-click onto sth., (to) doubleclick sth. - verb - - - drop-down list - combination box, combo box, combobox, dropdown, drop-down, + verb + + + drop-down list + combination box, combo box, combobox, dropdown, drop-down, drop-down menu, drop-down list box, popover, pull-down menu - noun; GUI element; the list that is opened when clicking on it, + noun; GUI element; the list that is opened when clicking on it, showing a list of menu items the user can choose from; if list entries start actions, use menu instead - - - DVD - D.V.D., Dvd - noun; acronym for + + + DVD + D.V.D., Dvd + noun; acronym for digital versatile disc - - - - dynamic name server - Dynamic Name Server, Dynamic name server - noun; acronym is DNS - - - - e-book - E-book, E-book, Ebook, eBook, electronic book, ebook - noun - - - e-mail - E-mail, E-mail, Email, eMail, electronic mail, email - noun - - - EPUB - E-PUB, e-PUB, e-Pub, EPub, Epub, ePUB, ePub - noun; project logo uses the capitalization ePub, + + + + dynamic name server + Dynamic Name Server, Dynamic name server + noun; acronym is DNS + + + + e-book + E-book, E-book, Ebook, eBook, electronic book, ebook + noun + + + e-mail + E-mail, E-mail, Email, eMail, electronic mail, email + noun + + + EPUB + E-PUB, e-PUB, e-Pub, EPub, Epub, ePUB, ePub + noun; project logo uses the capitalization ePub, but the vendor standard is EPUB - - - - end user - end-user - noun; avoid; where possible, replace with + + + + end user + end-user + noun; avoid; where possible, replace with user - - - - (to) enter sth. (into sth.) - - verb; only when a value needs to be specified and + + + + (to) enter sth. (into sth.) + + verb; only when a value needs to be specified and should be pressed afterward; where possible, replace with specify or provide - - - - Ethernet - ethernet - noun - - - Ethernet card - wired card [sounds as if wires attached to the card are meant] - - noun; card that connects to networks via Ethernet - - - - Ext3 - EXT3, EXT 3, Ext 3, Ext-3, ext 3, ext-3, ext3 - noun; use this capitalization for all versions of the Ext + + + + Ethernet + ethernet + noun + + + Ethernet card + wired card [sounds as if wires attached to the card are meant] + + noun; card that connects to networks via Ethernet + + + + Ext3 + EXT3, EXT 3, Ext 3, Ext-3, ext 3, ext-3, ext3 + noun; use this capitalization for all versions of the Ext file system standard; intentionally inconsistent with project standard to emphasize that this is a proper name - - - Ext4 - EXT4, EXT 4, Ext 4, Ext-4, ext 4, ext-4, ext4 - noun - - - file name - file-name, filename - noun - - - file server - file-server, fileserver - noun - - - file system - file-system, filesystem - noun - - - flavor - flavour [British] - noun - - - flash drive - flash disk, flash disc, USB disk, USB drive, + + + Ext4 + EXT4, EXT 4, Ext 4, Ext-4, ext 4, ext-4, ext4 + noun + + + file name + file-name, filename + noun + + + file server + file-server, fileserver + noun + + + file system + file-system, filesystem + noun + + + flavor + flavour [British] + noun + + + flash drive + flash disk, flash disc, USB disk, USB drive, USB stick - noun - - - form - - noun; a structured window, box or screen that contains numerous + noun + + + form + + noun; a structured window, box or screen that contains numerous fields or spaces to enter data - - - framebuffer - frame buffer, frame-buffer - noun - - - front-end - front end, frontend - noun - - - FTP - F.T.P., Ftp, ftp - noun - - - GIMP - G.I.M.P., Gimp, gimp - noun; spelling as per project standard; acronym for + + + framebuffer + frame buffer, frame-buffer + noun + + + front-end + front end, frontend + noun + + + FTP + F.T.P., Ftp, ftp + noun + + + GIMP + G.I.M.P., Gimp, gimp + noun; spelling as per project standard; acronym for GNU Image Manipulation Program; if the occurs directly before GIMP, capitalize it: The - - - - GNOME - G.N.O.M.E., GNU Networked Object Model Environment, + + + + GNOME + G.N.O.M.E., GNU Networked Object Model Environment, Gnome - noun; spelling as per project standard; not an acronym + noun; spelling as per project standard; not an acronym - - - GRUB - G.R.U.B., Grub, grub - noun; acronym for + + + GRUB + G.R.U.B., Grub, grub + noun; acronym for GRand Unified Bootloader - - - - graphical user interface - Graphical User Interface - noun; acronym for + + + + graphical user interface + Graphical User Interface + noun; acronym for graphical user interface - sknorr, 2013-09-16: Not completely sure about graphical UI + sknorr, 2013-09-16: Not completely sure about graphical UI - - - - GUI - G.U.I., GUI interface, GUI user interface, Gui - noun; acronym for + + + GUI + G.U.I., GUI interface, GUI user interface, Gui + + noun; acronym for graphical user interface - - - - hard disk - HDD, HD, hard disc [misspelling], hard disk drive, hard drive, + + + + hard disk + HDD, HD, hard disc [misspelling], hard disk drive, hard drive, hard-disk, hard-drive, harddisk, harddrive, hdd, hd - noun - - - hard link - hard-link, hardlink - only as a noun; as a verb, use + noun + + + hard link + hard-link, hardlink + only as a noun; as a verb, use create a hardlink link; directory entry that contains an alternative name for an existing file, in contrast to that, symbolic links are themselves files which link to the name of another file - - - home page - home-page, homepage - noun + + + home page + home-page, homepage + noun sknorr, 2013-09-16: I can't accept the accepted spelling. - - - - host name - host-name, hostname - noun - - - (to) hotplug sth. (into sth.) - (to) hot plug sth. (into sth.), (to) hot-plug sth. (into + + + + host name + host-name, hostname + noun + + + (to) hotplug sth. (into sth.) + (to) hot plug sth. (into sth.), (to) hot-plug sth. (into sth.), (to) hotadd sth., (to) hotswap sth. - verb; adding a component or device to a system while the + verb; adding a component or device to a system while the system is running; use remove at runtime where the specific action of removing a component or device is concerned - - - hotplugging - hot plugging, hot-plugging, hotadding, hotswapping - noun - - - hotpluggable - hot pluggable, hot-pluggable, hotaddable, hotswappable - adjective - - - HTML page - HTML document, HTML Web page, HTML web page - noun; when referring to a local file; see also + + + hotplugging + hot plugging, hot-plugging, hotadding, hotswapping + noun + + + hotpluggable + hot pluggable, hot-pluggable, hotaddable, hotswappable + adjective + + + HTML page + HTML document, HTML Web page, HTML web page + noun; when referring to a local file; see also Web page - - - - HTTP - H.T.T.P., Http, http - noun - - - HTTPS - H.T.T.P.S., Https, https - noun - - - hypervisor - hyper visor, hyper-visor, hypervizor - - noun - - - indexes - indices - noun; plural of index - - - infrared - infra red, infra-red - noun or adjective. + + + + HTTP + H.T.T.P., Http, http + noun + + + HTTPS + H.T.T.P.S., Https, https + noun + + + hypervisor + hyper visor, hyper-visor, hypervizor + + noun + + + indexes + indices + noun; plural of index + + + infrared + infra red, infra-red + noun or adjective. sknorr, 2013-09-16: Really a noun? - - - - init script - init-script, initscript, initialization script [incorrect, + + + + init script + init-script, initscript, initialization script [incorrect, when referring to script run by init] - noun; a script run by init; for noun; a script run by init; for systemd, use unit or unit file - - - - initialization - init, initialisation [British] - noun - - - (to) initialize sth. - (to) init sth., (to) initialise sth. [British] - verb - - - installation medium - installation data medium - noun; often in plural, installation media; + + + + initialization + init, initialisation [British] + noun + + + (to) initialize sth. + (to) init sth., (to) initialise sth. [British] + verb + + + installation medium + installation data medium + noun; often in plural, installation media; only for physical sources of installation data for products; when physicality of the installation source is unclear or unimportant, use the more versatile term installation source - - - - installation source - installation data source - + + + + installation source + installation data source + noun; source of installation data for products, can be a physical medium or online repository - - - Internet - internet - noun - - - intranet - Intranet - noun - - - I/O port - I.O. port, I-O port, IO port, Io port - noun - - - IA64 - IA-64, ia64, ipf, Itanium - noun; processor architecture - - - - IPsec - IPSEC, Ipsec - noun - - - IPv4 - IP v4, IPV4, Ipv4 - noun; acronym for Internet protocol version + + + Internet + internet + noun + + + intranet + Intranet + noun + + + I/O port + I.O. port, I-O port, IO port, Io port + noun + + + IA64 + IA-64, ia64, ipf, Itanium + noun; processor architecture + + + + IPsec + IPSEC, Ipsec + noun + + + IPv4 + IP v4, IPV4, Ipv4 + noun; acronym for Internet protocol version four - - - - IPv6 - IP v6, IPV6, Ipv6 - noun; acronym for Internet protocol version + + + + IPv6 + IP v6, IPV6, Ipv6 + noun; acronym for Internet protocol version six - - - - journaling - journalling [British] - noun - - - KIWI - Kiwi, kiwi - noun; project spelling; not an acronym; software for creation of + + + + journaling + journalling [British] + noun + + + KIWI + Kiwi, kiwi + noun; project spelling; not an acronym; software for creation of operating system images - - - K Desktop Environment - Kool Desktop Environment - noun; spelling according to project standard; acronym is + + + K Desktop Environment + Kool Desktop Environment + noun; spelling according to project standard; acronym is KDE - - - - KDE - KDE Desktop Environment, K.D.E., Kde, kde - noun; spelling according to project standard; acronym for + + + + KDE + KDE Desktop Environment, K.D.E., Kde, kde + noun; spelling according to project standard; acronym for K Desktop Environment - - - - Kdump - KDUMP, kdump - noun; only for application - - - kdump - KDUMP, Kdump - noun; only for command - - - - kernel space - kernel-space, kernelspace, kernelland - noun; memory area reserved for the kernel and device drivers; + + + + Kdump + KDUMP, kdump + noun; only for application + + + kdump + KDUMP, Kdump + noun; only for command + + + + kernel space + kernel-space, kernelspace, kernelland + noun; memory area reserved for the kernel and device drivers; see also user space - - - - key combination - hot key, key accelerator, keyboard accelerator, key combo, + + + + key combination + hot key, key accelerator, keyboard accelerator, key combo, keyboard combo, keyboard combination, key shortcut - noun - - - Kprobes - kprobes - noun; only for application - - - kprobes - Kprobes - noun; only for command - - - - (to) left-click sth. - (to) click the left mouse, (to) click the left mouse button, + noun + + + Kprobes + kprobes + noun; only for application + + + kprobes + Kprobes + noun; only for command + + + + (to) left-click sth. + (to) click the left mouse, (to) click the left mouse button, (to) left click sth., (to) left-click on sth., (to) left-click onto sth., (to) leftclick sth. - verb - - - left click - - noun - - - LibreOffice - Libre Office, Libreoffice, LibO, LO, libreoffice - noun; spelling according to project standard; do not create + verb + + + left click + + noun + + + LibreOffice + Libre Office, Libreoffice, LibO, LO, libreoffice + noun; spelling according to project standard; do not create acronyms of LibreOffice - - - - license - licence [British] - noun - - - (to) license sth. - (to) licence sth. [British] - verb - - - lifecycle - life cycle, life-cycle - noun; a series of development and support stages that a product + + + + license + licence [British] + noun + + + (to) license sth. + (to) licence sth. [British] + verb + + + lifecycle + life cycle, life-cycle + noun; a series of development and support stages that a product passes through - - - Linux - LINUX, linux - noun; spelling according to project standard - - - list - list field - noun; GUI element showing a list of menu items the user can choose from - - - - live CD - LiveCD, live-CD - noun; CD that allows booting an operating system without + + + Linux + LINUX, linux + noun; spelling according to project standard + + + list + list field + noun; GUI element showing a list of menu items the user can choose from + + + + live CD + LiveCD, live-CD + noun; CD that allows booting an operating system without installing - - - live DVD - LiveDVD, live-DVD - noun; DVD that allows booting an operating system without + + + live DVD + LiveDVD, live-DVD + noun; DVD that allows booting an operating system without installing - - - live image - live disk image, LiveImage, live-image - noun; disk image that can be copied to a medium and then allows + + + live image + live disk image, LiveImage, live-image + noun; disk image that can be copied to a medium and then allows booting an operating system without installing - - - local host - local-host, localhost - noun; when describing the concept of hosting locally - - - localhost - local host, local-host - noun; when referring to the default name of a local host - - - log file - log-file, logfile - noun - - - login - log in, log-in - noun - - - logout - log out, log-out - noun - - - (to) log in [see below for appropriate preposition] - (to) log-in, (to) login, (to) log on, (to) log-on, + + + local host + local-host, localhost + noun; when describing the concept of hosting locally + + + localhost + local host, local-host + noun; when referring to the default name of a local host + + + log file + log-file, logfile + noun + + + login + log in, log-in + noun + + + logout + log out, log-out + noun + + + (to) log in [see below for appropriate preposition] + (to) log-in, (to) login, (to) log on, (to) log-on, (to) logon, (to) sign in, (to) sign on - verb - - - (to) log in to sth. - (to) log in at sth., (to) log into sth. - verb; for logging in to a device, application, etc. - - - (to) log in on sth. - (to) log in at sth., (to) log in from sth. - verb; for logging in on the console/a host system - - - (to) log in (to sth.) via SSH - (to) log in (to sth.) by SSH, (to) log in (to sth.) over SSH, + verb + + + (to) log in to sth. + (to) log in at sth., (to) log into sth. + verb; for logging in to a device, application, etc. + + + (to) log in on sth. + (to) log in at sth., (to) log in from sth. + verb; for logging in on the console/a host system + + + (to) log in (to sth.) via SSH + (to) log in (to sth.) by SSH, (to) log in (to sth.) over SSH, (to) log in (to sth.) through SSH, (to) log in (to sth.) with SSH, (to) SSH (to sth.), (to) ssh (to sth.), (to) ssh in (to sth.), (to) ssh into sth., - verb - - - (to) log out [see below for appropriate preposition] - (to) log off, (to) log-out, (to) logout, (to) sign off, + verb + + + (to) log out [see below for appropriate preposition] + (to) log off, (to) log-out, (to) logout, (to) sign off, (to) sign out - verb - - - (to) log out of sth. - (to) log out at sth., (to) log out from sth. - verb - - - loopback device - loop back device, loop-back device - noun - - - lowercase - lower case, lower-case - noun - - - mail server - mail-server, mailserver - noun - - - Maildir - Mail dir, mail dir - noun; specific format for e-mail storage, not a directory for + verb + + + (to) log out of sth. + (to) log out at sth., (to) log out from sth. + verb + + + loopback device + loop back device, loop-back device + noun + + + lowercase + lower case, lower-case + noun + + + mail server + mail-server, mailserver + noun + + + Maildir + Mail dir, mail dir + noun; specific format for e-mail storage, not a directory for e-mails - - - mainboard - main board, main-board, mother board, mother-board, + + + mainboard + main board, main-board, mother board, mother-board, motherboard - noun - - - man page - manual page, Man page, Man-page, man page, man-page, manpage - two words - - - Mbox - mbox - noun; specific format for e-mail storage - - - menu - drop-down menu - noun; GUI element that is a list whose entries each start an + noun + + + man page + manual page, Man page, Man-page, man page, man-page, manpage + two words + + + Mbox + mbox + noun; specific format for e-mail storage + + + menu + drop-down menu + noun; GUI element that is a list whose entries each start an action; see also drop-down list - - - - metadata - meta data, meta-data, metadatas [misspelling] - noun - - - (to) middle-click sth. - (to) click the middle mouse, (to) click the middle mouse button, + + + + metadata + meta data, meta-data, metadatas [misspelling] + noun + + + (to) middle-click sth. + (to) click the middle mouse, (to) click the middle mouse button, (to) middle click sth., (to) middle-click on sth., (to) middle-click onto sth., (to) middleclick sth. - verb - - - middle click - - noun - - - mount point - mount-point, mountpoint - noun - - - mouse button - mouse-button, mousebutton, mouse key, mouse-key, mousekey - - noun - - - (to) multitask - (to) multi task, (to) multi-task - verb - - - multitasking - multi tasking, multi-tasking - noun - - - multiuser - multi user, multi-user - noun - - - multi-version - multi version, multiversion - adjective - - - name server - name-server, nameserver - noun - - - namespace - name space, name-space - noun - - - need to - have to - verb; see also must - - - - NFS - N.F.S., NFS file system, Nfs - noun; often: NFS client, - NFS server - - - - NIS - N.I.S., NIS information service, Nis - noun; often: NIS client, - NIS server - - - - OOo - Oo.o, Ooo, OOoo, OO, oo - noun; only when referring to versions prior to 3.4; spelling + verb + + + middle click + + noun + + + mount point + mount-point, mountpoint + noun + + + mouse button + mouse-button, mousebutton, mouse key, mouse-key, mousekey + + noun + + + (to) multitask + (to) multi task, (to) multi-task + verb + + + multitasking + multi tasking, multi-tasking + noun + + + multiuser + multi user, multi-user + noun + + + multi-version + multi version, multiversion + adjective + + + name server + name-server, nameserver + noun + + + namespace + name space, name-space + noun + + + need to + have to + verb; see also must + + + + NFS + N.F.S., NFS file system, Nfs + noun; often: NFS client,NFS server + + + + NIS + N.I.S., NIS information service, Nis + noun; often: NIS client,NIS server + + + + OOo + Oo.o, Ooo, OOoo, OO, oo + noun; only when referring to versions prior to 3.4; spelling according to former project standard; acronym of OpenOffice.org; see also AOO - - - - (to) open sth. - (to) open up sth. - verb - - - OpenOffice.org - Open Office Org, OpenOffice, Openoffice.org, + + + + (to) open sth. + (to) open up sth. + verb + + + OpenOffice.org + Open Office Org, OpenOffice, Openoffice.org, openoffice, openoffice.org - noun; only when referring to versions prior to 3.4; spelling + noun; only when referring to versions prior to 3.4; spelling according to former project standard; acronym is OOo; see also Apache OpenOffice - - - - openSUSE - Open SUSE, Open-SUSE, open SUSE, open-SUSE - noun; never capitalize first letter - - - open source - Open Source, Open-Source, open-source, opensource - only as a noun - - - operating system - operation system, operating-system - noun - - - paravirtualized - para-virtualised, paravirtualised [British], + + + + openSUSE + Open SUSE, Open-SUSE, open SUSE, open-SUSE + noun; never capitalize first letter + + + open source + Open Source, Open-Source, open-source, opensource + only as a noun + + + operating system + operation system, operating-system + noun + + + paravirtualized + para-virtualised, paravirtualised [British], para-virtualized - adjective - - - patch level - patch-level, patchlevel - noun - - - - path name - path-name, pathname - noun; avoid, check if path can be used + adjective + + + patch level + patch-level, patchlevel + noun + + + + path name + path-name, pathname + noun; avoid, check if path can be used instead - - - (to) plug sth. in - (to) plug-in sth., (to) plugin sth. - verb - - - plug-in - plug in, plugin - noun|adjective - - - pointer - cursor [used for keyboard input], mouse cursor - noun; on-screen item echoing the movement of a pointing device, + + + (to) plug sth. in + (to) plug-in sth., (to) plugin sth. + verb + + + plug-in + plug in, plugin + noun|adjective + + + pointer + cursor [used for keyboard input], mouse cursor + noun; on-screen item echoing the movement of a pointing device, such as a mouse; mouse pointer is also acceptable; see also cursor - - - - pop-up - pop up, popup - noun - - - on port - at port - noun with preposition - - - PostScript - POSTSCRIPT, Postscript, postscript - noun; spelling as per vendor standard - - - POWER - ppc64le, POWER8, Power - noun; processor architecture - - - - (to) preconfigure sth. - (to) pre-configure sth. - verb - - - preconfigured - pre-configured - adjective - - - (to) print sth. - (to) print out sth. - verb - - - print queue - printer queue, + + + + pop-up + pop up, popup + noun + + + on port + at port + noun with preposition + + + PostScript + POSTSCRIPT, Postscript, postscript + noun; spelling as per vendor standard + + + POWER + ppc64le, POWER8, Power + noun; processor architecture + + + + (to) preconfigure sth. + (to) pre-configure sth. + verb + + + preconfigured + pre-configured + adjective + + + (to) print sth. + (to) print out sth. + verb + + + print queue + printer queue, printing queue - noun - - - print spooler - printer spooler, + noun + + + print spooler + printer spooler, printing spooler - noun - - - (to) press sth. - (to) depress sth. [negative], (to) hit sth. [colloquial], + noun + + + (to) press sth. + (to) depress sth. [negative], (to) hit sth. [colloquial], (to) punch sth. [colloquial], (to) strike sth. [colloquial] - verb; when referring to keyboard keys or device buttons, but not + verb; when referring to keyboard keys or device buttons, but not mouse buttons; also see click - - - - program - - noun; a set of coded instructions that enables a machine, + + + + program + + noun; a set of coded instructions that enables a machine, especially a computer, to perform a desired sequence of operations - - - proxy - - only as a noun - - - PXE - P.X.E., Pixie, pixie, PXE Environment, Pxe, pxe - noun; acronym for + + + proxy + + only as a noun + + + PXE + P.X.E., Pixie, pixie, PXE Environment, Pxe, pxe + noun; acronym for Preboot Execution Environment - - - - PXE boot - PXE Boot - only as a noun; as a verb, use + + + + PXE boot + PXE Boot + only as a noun; as a verb, use (to) boot using PXE or (to) boot via PXE instead - - - (to) quit sth. - (to) abort sth., (to) exit sth., (to) kill sth., + + + (to) quit sth. + (to) abort sth., (to) exit sth., (to) kill sth., (to) terminate sth. - noun; quitting an application; always use + noun; quitting an application; always use close when referring to windows; always use terminate when ending an application forcefully - - - RAM - R.A.M., RAM memory, Ram, ram - noun; acronym for random access memory - - - - RAM disk - RAM disc [misspelling], RAM drive, RAM-disk, RAM-drive, RAMdisk, + + + RAM + R.A.M., RAM memory, Ram, ram + noun; acronym for random access memory + + + + RAM disk + RAM disc [misspelling], RAM drive, RAM-disk, RAM-drive, RAMdisk, RAM-drive, Ramdisk, Ramdrive - noun; either treating RAM as a hard disk or a + noun; either treating RAM as a hard disk or a type of solid-state storage - - - README - Read-me, Readme, read-me, readme - noun; use this capitalization for all general references - - - read-only - R.O., RO, read only, readonly, ro - adjective - - - real time - real-time - noun; as in watch in real time - - - real-time - real time - adjective, compound noun; as in real-time processing - - - (to) reconfigure sth. - (to) re-configure sth. - verb - - - (to) re-create sth. - (to) recreate [different meaning] - verb - - - (to) register [see below for appropriate preposition] - (to) sign up, (to) sign-up, (to) signup - verb; register as a user - - - (to) register at sth. - - verb; register at a system - - - (to) register for sth. - - verb; register for a service - - - (to) register to sth. - - verb; use when writing about registering to a server: - register to the RMT server - - - (to) register with sth. - - verb; use when writing about the tool used for registration: - register the domain with libvirt - - - (to) remove sth. at runtime (from sth.) - (to) hotremove sth. - verb; removing a component or device to a system while it is + + + README + Read-me, Readme, read-me, readme + noun; use this capitalization for all general references + + + read-only + R.O., RO, read only, readonly, ro + adjective + + + real time + real-time + noun; as in watch in real time + + + + real-time + real time + adjective, compound noun; as in real-time processing + + + + (to) reconfigure sth. + (to) re-configure sth. + verb + + + (to) re-create sth. + (to) recreate [different meaning] + verb + + + (to) register [see below for appropriate preposition] + (to) sign up, (to) sign-up, (to) signup + verb; register as a user + + + (to) register at sth. + + verb; register at a system + + + (to) register for sth. + + verb; register for a service + + + (to) register to sth. + + verb; use when writing about registering to a server: + register to the RMT server + + + + (to) register with sth. + + verb; use when writing about the tool used for registration: + register the domain with libvirt + + + + (to) remove sth. at runtime (from sth.) + (to) hotremove sth. + verb; removing a component or device to a system while it is running; where sensible, use the more generic term hotplug - - - - (to) right-click sth. - (to) click the right mouse, (to) click the right mouse button, + + + + (to) right-click sth. + (to) click the right mouse, (to) click the right mouse button, (to) right click sth., (to) right-click on sth., (to) right-click onto sth., (to) rightclick sth. - verb - - - right click - - noun - - - RPM - R.P.M., Rpm, rpm [different meaning] - noun; acronym for RPM Package Manager - - - - runlevel - run level, run-level - noun - - - runtime - run time, run-time - noun - - - Samba - SAMBA, samba - noun; project spelling; open-source implementation of the SMB file + verb + + + right click + + noun + + + RPM + R.P.M., Rpm, rpm [different meaning] + noun; acronym for RPM Package Manager + + + + runlevel + run level, run-level + noun + + + runtime + run time, run-time + noun + + + Samba + SAMBA, samba + noun; project spelling; open-source implementation of the SMB file and print service protocol - - - (to) save sth. - (to) store sth., (to) write sth. out - verb; when saving or overwriting a file from a GUI program or + + + (to) save sth. + (to) store sth., (to) write sth. out + verb; when saving or overwriting a file from a GUI program or via a parameter of a command-line program; see also write - - - - (to) save sth. as sth. - - verb; when saving a file with a specific name - - - - (to) save sth. in sth. - - verb; when saving a file either on a specific device or file + + + + (to) save sth. as sth. + + verb; when saving a file with a specific name + + + + (to) save sth. in sth. + + verb; when saving a file either on a specific device or file system - - - (to) save sth. on sth. - - verb; when saving a file either on a specific device or file + + + (to) save sth. on sth. + + verb; when saving a file either on a specific device or file system - - - (to) save sth. to sth. - - verb; when saving a file to a specific folder - - - - saved in sth. - - verb; when retrieving a file from a specific place - - - - SCSI - S.C.S.I., Scsi, scsi - noun - - - screen - - noun; the surface on which the image appears in an + + + (to) save sth. to sth. + + verb; when saving a file to a specific folder + + + + saved in sth. + + verb; when retrieving a file from a specific place + + + + SCSI + S.C.S.I., Scsi, scsi + noun + + + screen + + noun; the surface on which the image appears in an electronic display (as in a computer terminal); also the information displayed on a computer screen at one time - - - screenshot - screen shot, screen-shot - noun - - - screen saver - screen-saver, screensaver - noun - - - script - - noun; a prewritten list of commands, and perhaps other control + + + screenshot + screen shot, screen-shot + noun + + + screen saver + screen-saver, screensaver + noun + + + script + + noun; a prewritten list of commands, and perhaps other control information, to be executed (interpreted) by a shell or other command interpreter - - - scrollbar - scroll-bar, scroll bar, scrollbox, + + + scrollbar + scroll-bar, scroll bar, scrollbox, scroller, slidebar - noun; GUI element that is used to change which portion of a + noun; GUI element that is used to change which portion of a screen area is visible - - - (to) select sth. - (to) block sth., (to) choose sth., (to) highlight sth. + + + (to) select sth. + (to) block sth., (to) choose sth., (to) highlight sth. - verb; when referring to list entries or text; for check boxes, + verb; when referring to list entries or text; for check boxes, use activate - - - - selected - blocked, chosen, highlighted - adjective; selection state of list entries or text; opposite of + + + + selected + blocked, chosen, highlighted + adjective; selection state of list entries or text; opposite of deselected - - - - (to) set sth. up - (to) set-up sth., (to) setup sth. - verb - - - setup - set up, set-up - adjective|noun - - - shell - - noun; a command-line interpreter used to describe + + + + (to) set sth. up + (to) set-up sth., (to) setup sth. + verb + + + setup + set up, set-up + adjective|noun + + + shell + + noun; a command-line interpreter used to describe programs that expose the input/output to the user (bash, sh, zsh) and to refer to the command prompt; - see also console, terminal - - - (to) shut sth. down - (to) shut-down sth., (to) shutdown sth. - verb - - - shutdown - shut down, shut-down - adjective|noun - - - SLE - S.L.E., SLE Enterprise, SLE Linux, Sle, sle - noun; avoid; acronym for + see also console, terminal + + + + (to) shut sth. down + (to) shut-down sth., (to) shutdown sth. + verb + + + shutdown + shut down, shut-down + adjective|noun + + + SLE + S.L.E., SLE Enterprise, SLE Linux, Sle, sle + noun; avoid; acronym for SUSE Linux Enterprise - - - - SLED - S.L.E.D., SLE Desktop, SLE Enterprise Desktop, + + + + SLED + S.L.E.D., SLE Desktop, SLE Enterprise Desktop, SLE Linux Desktop, Sled, sled - noun; avoid; acronym for + noun; avoid; acronym for SUSE Linux Enterprise Desktop - - - - SLES - S.L.E.S., SLE Server, SLE Enterprise Server, + + + + SLES + S.L.E.S., SLE Server, SLE Enterprise Server, SLE Linux Server, Sles, sles - noun; avoid; acronym for + noun; avoid; acronym for SUSE Linux Enterprise Server - - - - SLES for SAP - SLES for SAP Applications, SLE for SAP - noun; acronym for SUSE Linux Enterprise Server for + + + + SLES for SAP + SLES for SAP Applications, SLE for SAP + noun; acronym for SUSE Linux Enterprise Server for SAP Applications - - - - slider - slide bar, slidebar - noun; GUI element that is used manipulate values that have + + + + slider + slide bar, slidebar + noun; GUI element that is used manipulate values that have an upper and a lower bound sknorr, 2013-09-17: A little complicated - - - - solid-state drive - SD [misleading], solid state disc [misspelling], + + + + solid-state drive + SD [misleading], solid state disc [misspelling], solid-state disk drive, solid-state disk, solid state drive, solidstate drive, sd - noun; acronym is SSD; a type of + noun; acronym is SSD; a type of mass storage that does not depend on mechanical parts sknorr, 2014-04-09: This is inconsistent with the use of ... drive in most other cases. For now, intentionally so, as the accepted term gives much more on Google. Review this entry. - - - - spec file - Spec file, Spec-file, Specfile, spec-file, specfile - - noun - - - SSD - S.S.D., SD [misleading], SS-D, sd, ss-d - noun; acronym of solid-state + + + + spec file + Spec file, Spec-file, Specfile, spec-file, specfile + + noun + + + SSD + S.S.D., SD [misleading], SS-D, sd, ss-d + noun; acronym of solid-state drive; a type of mass storage that does not depend on mechanical parts - - - stand-alone - stand alone, standalone - adjective - - - (to) start sth. up - (to) start-up sth., (to) startup sth. - verb - - - start-up - start up, startup - noun - - - statusbar - status bar, status-bar - noun - - - SSH - S.S.H., SSH Shell, SSH shell, Ssh, ssh - noun - - - SUSE - S.U.S.E., Software- und System-Entwicklung, SuSE, SuSe, + + + stand-alone + stand alone, standalone + adjective + + + (to) start sth. up + (to) start-up sth., (to) startup sth. + verb + + + start-up + start up, startup + noun + + + statusbar + status bar, status-bar + noun + + + SSH + S.S.H., SSH Shell, SSH shell, Ssh, ssh + noun + + + SUSE + S.U.S.E., Software- und System-Entwicklung, SuSE, SuSe, Suse, suse - noun; not an acronym - - - SUSE Enterprise Storage - SUSE Storage, SUSE Linux Enterprise Storage - noun; acronym is SES - - - SUSE Linux Enterprise - SUSE Linux Entreprise [British], SUSE Linux enterprise, + noun; not an acronym + + + SUSE Enterprise Storage + SUSE Storage, SUSE Linux Enterprise Storage + noun; acronym is SES + + + + SUSE Linux Enterprise + SUSE Linux Entreprise [British], SUSE Linux enterprise, SUSE linux enterprise - noun; acronym is SLE - - - - SUSE Linux Enterprise Desktop - SUSE Desktop, SUSE Linux Enterprise desktop - noun; acronym is SLED - - - - SUSE Linux Enterprise Server - SUSE Server, SUSE Linux Enterprise server - noun; acronym is SLES - - - - SUSE Linux Enterprise Server for SAP Applications - SUSE Linux Enterprise for SAP, SUSE Linux Enterprise Server for + noun; acronym is SLE + + + + SUSE Linux Enterprise Desktop + SUSE Desktop, SUSE Linux Enterprise desktop + noun; acronym is SLED + + + + SUSE Linux Enterprise Server + SUSE Server, SUSE Linux Enterprise server + noun; acronym is SLES + + + + SUSE Linux Enterprise Server for SAP Applications + SUSE Linux Enterprise for SAP, SUSE Linux Enterprise Server for SAP, SUSE Server for SAP - noun; acronym is SLES for SAP Applications - - - - SUSE Manager - SUSE Linux Manager - noun - - - SUSE OpenStack Cloud - SUSE Cloud, SUSE Linux Cloud - noun - - - SUSE Studio - SUSE Linux Studio - noun - - - submenu - sub menu, sub-menu - noun; menu that is nested inside another + noun; acronym is SLES for SAP Applications + + + + SUSE Manager + SUSE Linux Manager + noun + + + SUSE OpenStack Cloud + SUSE Cloud, SUSE Linux Cloud + noun + + + SUSE Studio + SUSE Linux Studio + noun + + + submenu + sub menu, sub-menu + noun; menu that is nested inside another menu - - - subsystem - sub system, sub-system - noun - - - systemd - System D, Systemd, systemD, system d, System 500 - noun; project spelling; initialization system for Linux - - - - System V init - SysVinit, SysV init, system 5 init, system d - noun; spoken: System five init; + + + subsystem + sub system, sub-system + noun + + + systemd + System D, Systemd, systemD, system d, System 500 + noun; project spelling; initialization system for Linux + + + + System V init + SysVinit, SysV init, system 5 init, system d + noun; spoken: System five init; initialization system for Unix operating systems - - - system-wide - systemwide, system wide - adjective - - - symbolic link - soft link, softlink, symlink [jargon] - only as a noun; as a verb, use + + + system-wide + systemwide, system wide + adjective + + + symbolic link + soft link, softlink, symlink [jargon] + only as a noun; as a verb, use create a symbolic link; a file with a reference to another file or a directory, in contrast to that, a hard link is a directory entry that contains an alternative name for an existing file - - - synchronization - sync, synch, synchronisation [British] - noun; two-way or many-way copying process to ensure data is + + + synchronization + sync, synch, synchronisation [British] + noun; two-way or many-way copying process to ensure data is consistent across two or more locations - - - (to) synchronize sth. (with sth.) - (to) sync sth., (to) synch sth., (to) synchronise sth. + + + (to) synchronize sth. (with sth.) + (to) sync sth., (to) synch sth., (to) synchronise sth. [British], (to) synchronize sth. (and sth.) - noun; copy data in two or more ways to ensure it is + noun; copy data in two or more ways to ensure it is consistent across two or more locations - - - TAR archive - TAR ball [Unix jargon], tar ball, tar-ball, tarball - - noun - - - taskbar - task bar, task-bar - noun - - - technology preview - technical preview, technology-preview - noun; product features that are shipped without support and marked + + + TAR archive + TAR ball [Unix jargon], tar ball, tar-ball, tarball + + noun + + + taskbar + task bar, task-bar + noun + + + technology preview + technical preview, technology-preview + noun; product features that are shipped without support and marked as such - - - text box - entry area, entry box, entry field, input area, input box, + + + text box + entry area, entry box, entry field, input area, input box, input field, text area, text field - noun; GUI element that text can be typed into with one or + noun; GUI element that text can be typed into with one or more lines - - - terminal - - noun; text input/output environment where users interact + + + terminal + + noun; text input/output environment where users interact with Linux and Linux applications; the default term to describe a text-only user interface - - - (to) terminate sth. - (to) abort sth., (to) close sth., (to) exit sth., + + + (to) terminate sth. + (to) abort sth., (to) close sth., (to) exit sth., (to) kill sth., (to) quit sth. - noun; ending an application forcefully; always use + noun; ending an application forcefully; always use close when referring to windows; always use quit when ending an application normally - - - TFTP - T.F.T.P., Tftp, tftp - noun - - - timeout - time-out - noun - - - time stamp - time-stamp, timestamp - noun - - - titlebar - title bar, title-bar - noun - - - tool - - noun; a utility or feature used to develop software or + + + TFTP + T.F.T.P., Tftp, tftp + noun + + + timeout + time-out + noun + + + time stamp + time-stamp, timestamp + noun + + + titlebar + title bar, title-bar + noun + + + tool + + noun; a utility or feature used to develop software or hardware, or to perform particular tasks - - - toolbar - tool bar, tool-bar - noun - - - toolchain - tool chain, tool-chain - noun; set of tools (such as build tools) that is used in + + + toolbar + tool bar, tool-bar + noun + + + toolchain + tool chain, tool-chain + noun; set of tools (such as build tools) that is used in succession - - - tooltip - tool tip, tool-tip - noun - - - UEFI - Uefi, u-EFI, uEFI - noun; acronym of Unified Extensible Firmware + + + tooltip + tool tip, tool-tip + noun + + + UEFI + Uefi, u-EFI, uEFI + noun; acronym of Unified Extensible Firmware Interface - - - - Unified Extensible Firmware Interface - unified extensible firmware interface - noun; acronym is UEFI; software interface + + + + Unified Extensible Firmware Interface + unified extensible firmware interface + noun; acronym is UEFI; software interface between firmware and operating system; replaces the BIOS interface - - - unit - unit file - noun; + + + unit + unit file + noun; concept of systemd; generic term for services, timers, etc.; use when starting, stopping, enabling or disabling a unit - - - unit file - unit - noun; configuration file of a + + unit file + unit + noun; configuration file of a systemd unit; has a suffix (.service, .timer, etc.); only use when referring to the actual file (e.g. when editing it) and not the unit - - - Unix - UNIX [brand name registered by Open Group], + + + Unix + UNIX [brand name registered by Open Group], unix - noun; use this capitalization for all general references + noun; use this capitalization for all general references that are not related to brand names - - - (to) uninstall sth. - (to) deinstall sth., (to) un-install sth. + + + (to) uninstall sth. + (to) deinstall sth., (to) un-install sth. - verb + verb sknorr, 2013-09-17: Packages are usually "removed," not uninstalled (say YaST and zypper, but also my intuition). Should this word be restricted to Windows software? - - - - unselected - deselected, un-selected - adjective; selection state of list entries or text; opposite of + + + + unselected + deselected, un-selected + adjective; selection state of list entries or text; opposite of selected - - - - uppercase - upper case, upper-case - noun - - - usage - - noun; the way in which something is used, or the amount of - it that is used; see also utilization - - - use case - use-case, usecase - noun - - - (to) use sth. - (to) utilise sth. [British], (to) utilize sth. - verb - - - user name - user-name, username - noun - - - user space - user-space, userspace, userland - noun; memory area used by applications; see also + + + + uppercase + upper case, upper-case + noun + + + usage + + noun; the way in which something is used, or the amount of + it that is used; see also utilization + + + + use case + use-case, usecase + noun + + + (to) use sth. + (to) utilise sth. [British], (to) utilize sth. + verb + + + user name + user-name, username + noun + + + user space + user-space, userspace, userland + noun; memory area used by applications; see also kernel space - - - - utilization - utilisation [British] - noun; an act or instance of making practical or + + + + utilization + utilisation [British] + noun; an act or instance of making practical or profitable use of something, especially in CPU utilization, - memory utilization - - - - video DVD - Video DVD, Video-DVD, DVD video - noun - - - view - - noun; a reusable set of user interface widgets that serve as an + memory utilization + + + + video DVD + Video DVD, Video-DVD, DVD video + noun + + + view + + noun; a reusable set of user interface widgets that serve as an interface for user interaction - - - virtualization - Virtualization, virtualisation [British] + + + virtualization + Virtualization, virtualisation [British] - noun; referring to software (usually an operating system) + noun; referring to software (usually an operating system) running on a virtual computer created by software running on a physical computer or virtual computer created with software running on a physical computer - - - (to) virtualize sth. - virtualise [British] - verb; running software (usually an operating system) on a + + + (to) virtualize sth. + virtualise [British] + verb; running software (usually an operating system) on a virtual computer created by software running on a physical computer or creating a virtual computer with software running on a physical computer - - - VLAN - V.L.A.N., Vlan, vlan - noun; acronym for + + + VLAN + V.L.A.N., Vlan, vlan + noun; acronym for Virtualized Local Area Network - - - - Web - WEB, World Wide Web, WWW, web, www - noun; you may use World Wide Web or + + + + Web + WEB, World Wide Web, WWW, web, www + noun; you may use World Wide Web or WWW in historical contexts - - - Web cam - Webcam, Web camera, webcam - noun; camera that can be connected to a computer, mainly for + + + Web cam + Webcam, Web camera, webcam + noun; camera that can be connected to a computer, mainly for video chats - - - Web page - HTML Web page, Web-page, Webpage - noun; when referring to page on the Internet; see also + + + Web page + HTML Web page, Web-page, Webpage + noun; when referring to page on the Internet; see also HTML page - - - - Web server - Web-server, Webserver - noun - - - Web site - Web-site, Website, web site, web-site, website - noun - - - Webmaster - Web master, Web-master - noun - - - whitespace - white-space, white space - noun - - - Wi-Fi - Wi fi, Wi-fi, Wifi, wireless fidelity, WLAN - noun; use the Wi-Fi brand name + + + + Web server + Web-server, Webserver + noun + + + Web site + Web-site, Website, web site, web-site, website + noun + + + Webmaster + Web master, Web-master + noun + + + whitespace + white-space, white space + noun + + + Wi-Fi + Wi fi, Wi-fi, Wifi, wireless fidelity, WLAN + noun; use the Wi-Fi brand name whenever referring to IEEE 802.11-based networks or access points; use WLAN when referring to non-IEEE 802.11-based wireless LANs - - - Wi-Fi card - wireless card [card has wires attached to it] - noun; card that connects to Wi-Fi networks - - - - Wi-Fi/Bluetooth card - wireless card [card has wires attached to it] - noun; card that combines a Wi-Fi and a Bluetooth card - - - - wild card - joker [Germanism], wild-card, wildcard - noun - - - WLAN - Wlan - noun; avoid; use only when referring to wireless LANs that are + + + Wi-Fi card + wireless card [card has wires attached to it] + noun; card that connects to Wi-Fi networks + + + + Wi-Fi/Bluetooth card + wireless card [card has wires attached to it] + noun; card that combines a Wi-Fi and a Bluetooth card + + + + wild card + joker [Germanism], wild-card, wildcard + noun + + + WLAN + Wlan + noun; avoid; use only when referring to wireless LANs that are not IEEE 802.11-based; use Wi-Fi in all other cases - - - (to) write sth. - (to) pipe sth. [Unix jargon], + + + (to) write sth. + (to) pipe sth. [Unix jargon], (to) write sth. out - verb; when saving the command-line output of a program as a + verb; when saving the command-line output of a program as a file using > or >>; see also save - - - - x86 - 32-bit AMD/Intel, i686, i386 - noun; processor architecture; see also + + + + x86 + 32-bit AMD/Intel, i686, i386 + noun; processor architecture; see also AMD64/Intel 64 - - - - X Window System - X Window, X Windows, X window, X window system, X windows, XWS - noun + + + + X Window System + X Window, X Windows, X window, X window system, X windows, XWS + noun sknorr, 2013-09-17: What about X11, X.org, XFree86? - - - - Xen - XEN, xen - noun - - - Xend - xend - noun - - - YaST - YAST, YAST2, Yast, YaST2, yast, yast2 - noun; spelling according to project standard; acronym for + + + + Xen + XEN, xen + noun + + + Xend + xend + noun + + + YaST + YAST, YAST2, Yast, YaST2, yast, yast2 + noun; spelling according to project standard; acronym for Yet another Setup Tool - - - - IBM Z - z Systems, System z, zSeries, z System, zsystems, S390x - noun; processor architecture; see also + + + + IBM Z + z Systems, System z, zSeries, z System, zsystems, S390x + noun; processor architecture; see also AMD64/Intel 64 - - - - Zypper - zypper - noun; only for application - - - zypper - Zypper - noun; only for command - - - - - - - General vocabulary - - - The following table defines the correct spellings and denominations for - general vocabulary in SUSE documentation. Always use the entry listed - under Accepted in the table below. All entries are - reproduced in sentence-style capitalization. - + + + + Zypper + zypper + noun; only for application + + + zypper + Zypper + noun; only for command + + + + + + + General vocabulary - - Review the word list of the Inclusive Naming Initiative - - In addition to the words documented here, make sure to also review the - Word lists of the Inclusive Naming Initiative's - Evaluation Framework. - For more information about word choices, see . - - + The following table defines the correct spellings and denominations for + general vocabulary in SUSE documentation. Always use the entry listed + under Accepted in the table below. All entries are + reproduced in sentence-style capitalization. + - - - - - Accepted - Rejected [Reason] - Part of Speech; Usage Guideline/Definition - - - - - - after - once - adverb; only use once in the meaning + + Review the word list of the Inclusive Naming Initiative + + In addition to the words documented here, make sure to also review the + Word lists of the Inclusive Naming Initiative's + Evaluation + Framework. + + + For more information about word choices, see + . + + + + + + + + Accepted + Rejected [Reason] + Part of Speech; Usage Guideline/Definition + + + + + + after + once + adverb; only use once in the meaning of one time only - - - - afterward - afterwards [BrE] - adverb - - - - although - while - conjunction; only use while in the + + + + afterward + afterwards [BrE] + adverb + + + + although + while + conjunction; only use while in the meaning of during the time that - - - - and - while - conjunction; only use while in the + + + + and + while + conjunction; only use while in the meaning of during the time that - - - - backward - backwards [BrE] - adverb - - - - - basically [filler] - adverb - - - because of - since, due to, owing to - preposition; only use since in temporal phrases - - - business case - business-case, businesscase - noun - - - but - while - conjunction; only use while in the + + + + backward + backwards [BrE] + adverb + + + + + basically [filler] + adverb + + + because of + since, due to, owing to + preposition; only use since in temporal phrases + + + business case + business-case, businesscase + noun + + + but + while + conjunction; only use while in the meaning of during the time that - - - - cannot - can't [contraction], can not - verb - - - can - may - verb; use can to express an ability, + + + + cannot + can't [contraction], can not + verb + + + can + may + verb; use can to express an ability, only use may to express permissions sought/given - - - could - may - verb; use could to express a + + + could + may + verb; use could to express a possibility, only use may to express permissions sought/given - - - data is - data are - noun with verb; use all other verbs in the singular + + + data is + data are + noun with verb; use all other verbs in the singular - - - - easy [filler], easily - adjective, adverb; avoid - - - - etc. - - abbreviation; avoid; do not use together with + + + + easy [filler], easily + adjective, adverb; avoid + + + + etc. + + abbreviation; avoid; do not use together with for example and such as; always precede with a comma - - - for example - for instance, for instances [misspelling] - adverb - - - - forward - forwards [BrE] - adverb - - - - if - - pronoun; use if an event depends on a condition; also see + + + for example + for instance, for instances [misspelling] + adverb + + + + forward + forwards [BrE] + adverb + + + + if + + pronoun; use if an event depends on a condition; also see when and whether - - - - inward - inwards [BrE] - adverb - - - - - just [filler] - adjective, adverb; avoid - - - might - may - verb; use might to express a + + + + inward + inwards [BrE] + adverb + + + + + just [filler] + adjective, adverb; avoid + + + might + may + verb; use might to express a possibility, only use may to express permissions sought/given - - - must - have to - verb; see also need to - - - - need to - have to - verb; see also must - - - - - obvious [insulting], obviously - adjective, adverb - - - outward - outwards [BrE] - adverb - - - - - please - adverb; avoid - - - - self-evident [insulting], self-evidently - adjective, adverb - - - sideward - sidewards [BrE] - adverb - - - - - simple [filler], simply - adjective, adverb; avoid - - - (to) simplify sth. - (to) ease sth., (to) facilitate sth. - verb; avoid - - - (to) simplify sth. - (to) ease sth., (to) facilitate sth. - verb; avoid - - - - stuff [colloquial], stuffs - noun - - - toward - towards [BrE] - adverb - - - - want sth. - (to) wish sth., (to) wish for sth., would like sth. - verb - - - when - once - adverb; use once only in the meaning + + + must + have to + verb; see also need to + + + + need to + have to + verb; see also must + + + + + obvious [insulting], obviously + adjective, adverb + + + outward + outwards [BrE] + adverb + + + + + please + adverb; avoid + + + + self-evident [insulting], self-evidently + adjective, adverb + + + sideward + sidewards [BrE] + adverb + + + + + simple [filler], simply + adjective, adverb; avoid + + + (to) simplify sth. + (to) ease sth., (to) facilitate sth. + verb; avoid + + + (to) simplify sth. + (to) ease sth., (to) facilitate sth. + verb; avoid + + + + stuff [colloquial], stuffs + noun + + + toward + towards [BrE] + adverb + + + + want sth. + (to) wish sth., (to) wish for sth., would like sth. + verb + + + when + once + adverb; use once only in the meaning one time only - - - - when - - pronoun; use if an event is inevitable; also see + + + + when + + pronoun; use if an event is inevitable; also see if - - - - whether - whether or not - pronoun; use to present two alternatives which are not + + + + whether + whether or not + pronoun; use to present two alternatives which are not conditions, otherwise use if; see also if - sknorr, 2014-02-18: This is helpful: + sknorr, 2014-02-18: This is helpful: https://www.grammar-monster.com/easily_confused/if_and_whether.htm - - - - regarding - as regards, in regard to, with regard to, with regards to - preposition - - - - - + + + + regarding + as regards, in regard to, with regard to, with regards to + preposition + + + + + diff --git a/xml/docu_styleguide.webwriting.xml b/xml/docu_styleguide.webwriting.xml index 8c8852b6..d9485f86 100644 --- a/xml/docu_styleguide.webwriting.xml +++ b/xml/docu_styleguide.webwriting.xml @@ -5,88 +5,86 @@ %entities; ]> - Writing for the Web - - - Create engaging and informative content that helps your audience and is - optimized for the Web. - - -
- Topical structure + Writing for the Web - The most important thing to do with your Web copy is to help users get - answers to their questions as soon as possible. To achieve this, we - recommend the modular approach of topic-based authoring where documentation - is created and maintained in chunks, subsequently referred to as topics. + Create engaging and informative content that helps your audience and is + optimized for the Web. - - Topics have the sole purpose of supporting users in their tasks. Each topic - focuses on one specific subject and has one distinct purpose. We write - topics in a way that they can stand alone as well as in context with other - topics. They should also be reusable in different contexts. - - - Recommendations: - - - +
+ Topical structure - Put your most important information first. Users typically decide if they - are going to stay on your page within 3–5 seconds. Make sure your - copy helps users understand the big picture right away. + The most important thing to do with your Web copy is to help users get + answers to their questions as soon as possible. To achieve this, we + recommend the modular approach of topic-based authoring where + documentation is created and maintained in chunks, subsequently referred + to as topics. - - - Write for scanners. Help readers find the answer to their question. Create - headlines that are clear and to the point. Break long headlines into a - heading and sub-head. Ask yourself: Is it easy to see the benefit of the - page with a quick glance? + Topics have the sole purpose of supporting users in their tasks. Each + topic focuses on one specific subject and has one distinct purpose. We + write topics in a way that they can stand alone as well as in context + with other topics. They should also be reusable in different contexts. - - - Organize content logically. Layer and break up your content into sections - to help users find answers at a glance. + Recommendations: - - -
- -
- Writing SEO-friendly content - - SEO, or Search Engine Optimization, is the strategy to attract organic - (unpaid) traffic that originates from online search and refers to visitors - landing on the Web site. When it comes to SEO, content is key. Here are some - insights to help you create and design the content that will rank high in - search engines. - - - - Brainstorm and research keywords - - - To learn what type of content search engines deem best for a specific - keyword, search the phrases you want to rank for. Bear in mind the - approved &suse; documentation terminology. - - - At the same time, do not stuff your content with keywords. The keyword - ratio for an article should be 2–4%, that is, 8–10 keywords - per 500 words. - - - - - Structure your content in a way that is easy for users to scan - - - Structuring your headings in a hierarchy can make a larger content piece - easily scannable while helping search engines understand the context of - your content. For example: - + + + + Put your most important information first. Users typically decide if + they are going to stay on your page within 3–5 seconds. Make + sure your copy helps users understand the big picture right away. + + + + + Write for scanners. Help readers find the answer to their question. + Create headlines that are clear and to the point. Break long + headlines into a heading and sub-head. Ask yourself: Is it easy to + see the benefit of the page with a quick glance? + + + + + Organize content logically. Layer and break up your content into + sections to help users find answers at a glance. + + + +
+
+ Writing SEO-friendly content + + SEO, or Search Engine Optimization, is the strategy to attract organic + (unpaid) traffic that originates from online search and refers to + visitors landing on the Web site. When it comes to SEO, content is key. + Here are some insights to help you create and design the content that + will rank high in search engines. + + + + Brainstorm and research keywords + + + To learn what type of content search engines deem best for a + specific keyword, search the phrases you want to rank for. Bear in + mind the approved &suse; documentation terminology. + + + At the same time, do not stuff your content with keywords. The + keyword ratio for an article should be 2–4%, that is, + 8–10 keywords per 500 words. + + + + + Structure your content in a way that is easy for users to scan + + + Structuring your headings in a hierarchy can make a larger content + piece easily scannable while helping search engines understand the + context of your content. For example: + <H1> Dealing with Boot and Installation Problems <H2> Problems Booting <H3> Solution 1 @@ -95,153 +93,156 @@ <H3> Solution 1 <H3> Solution 2 - - - - Create concise and meaningful title tags and meta descriptions - - - Search engines pull the title tag, or meta title, from H1, and the meta - description from the abstract. The number of characters is limited, and - the recommended length for meta titles is 55–65 characters. - However, they must not be shorter than 29 characters. Be sure to optimize your - headings wherever appropriate by integrating keywords, such as product - names, into them. The optimal length for meta descriptions is 145–155 characters. - - - Product names are known for their extra length, so effective page titles - and meta descriptions may require the use of abbreviations. From the - search engine perspective, it can be helpful to mention the abbreviation - within the content by adding the abbreviation in parenthesis after the - first use of the term. - - - - - Link from (and to) your content - - - Links are critical to establishing the authority and relevance of your - content. The two most important types of links are: - - - - - Internal links lead to and from other pages within the same domain and - help establish the relationship between two pieces of content. Internal - linking helps search engines discover new pages on the Web site and - index them. - - - - - Inbound links lead to your content piece from a different domain (for - example, SAP.com to SUSE.com). - - - - - External links to high-quality, creditable Web sites help increase the - validity of your own Web site. The better the links, the higher the page - ranks in search results. - - - - - Optimize images by adding alt text - - - Be sure to add alternative text whenever you use images. This practice - allows search engines to understand the context of your images and index - them more accurately. It also improves the accessibility of the Web site. - - - - -
- -
- Writing for a global audience - - Remember that every document is a potential candidate for localization (translation). - Make sure the document’s original English content is correct and clear. Simplicity, - clarity and direct prose are essential. - - - Recommendations: - - - - - Keep sentences short. Shorter sentences help translators and target audience to - better understand the content. - - - - - Be consistent. Stick to the terminology and use the same sentence structure for - similar content. Use the same sentences for repetitive texts. This helps to improve - the translation memory leverage. - - - - - Use proofreading and review options. Have your content reviewed to detect - misunderstandings in advance. - - - + + + + Create concise and meaningful title tags and meta descriptions + + + Search engines pull the title tag, or meta title, from H1, and the + meta description from the abstract. The number of characters is + limited, and the recommended length for meta titles is 55–65 + characters. However, they must not be shorter than 29 characters. + Be sure to optimize your headings wherever appropriate by + integrating keywords, such as product names, into them. The optimal + length for meta descriptions is 145–155 characters. + + + Product names are known for their extra length, so effective page + titles and meta descriptions may require the use of abbreviations. + From the search engine perspective, it can be helpful to mention + the abbreviation within the content by adding the abbreviation in + parenthesis after the first use of the term. + + + + + Link from (and to) your content + + + Links are critical to establishing the authority and relevance of + your content. The two most important types of links are: + + + + + Internal links lead to and from other pages within the same + domain and help establish the relationship between two pieces + of content. Internal linking helps search engines discover new + pages on the Web site and index them. + + + + + Inbound links lead to your content piece from a different + domain (for example, SAP.com to SUSE.com). + + + + + External links to high-quality, creditable Web sites help increase + the validity of your own Web site. The better the links, the higher + the page ranks in search results. + + + + + Optimize images by adding alt text + + + Be sure to add alternative text whenever you use images. This + practice allows search engines to understand the context of your + images and index them more accurately. It also improves the + accessibility of the Web site. + + + + +
+
+ Writing for a global audience - Keep it clear. Make clear statements and avoid should, - could and similar unprecise words. + Remember that every document is a potential candidate for localization + (translation). Make sure the document’s original English content is + correct and clear. Simplicity, clarity and direct prose are essential. - - - Mark non-translatable text. Use tags as defined in - or use the ITS tag feature to mark all content that should not be translated - (for more information, see ). - Use entities for product names, example names, etc. Always mark code - as such so that it is not translated. + Recommendations: - - - - Write for the world (if possible). Do not use country-specific words and examples. - Use common international examples instead. - - - - - Use only as many graphics as needed. As each graphic or screenshot needs - to be localized as well, keep it to the minimum. - - - - - Do not break sentences. Do not use hard breaks within a sentence. - - - - - Do not break your sentence with lists. For example, do not structure the - phrase like this: - - You can use the following commands: + + + + Keep sentences short. Shorter sentences help translators and target + audience to better understand the content. + + + + + Be consistent. Stick to the terminology and use the same sentence + structure for similar content. Use the same sentences for repetitive + texts. This helps to improve the translation memory leverage. + + + + + Use proofreading and review options. Have your content reviewed to + detect misunderstandings in advance. + + + + + Keep it clear. Make clear statements and avoid should, + could and similar unprecise words. + + + + + Mark non-translatable text. Use tags as defined in + or use the ITS tag feature to mark all + content that should not be translated (for more information, see + ). Use entities for product names, + example names, etc. Always mark code as such so that it is not + translated. + + + + + Write for the world (if possible). Do not use country-specific words + and examples. Use common international examples instead. + + + + + Use only as many graphics as needed. As each graphic or screenshot + needs to be localized as well, keep it to the minimum. + + + + + Do not break sentences. Do not use hard breaks within a sentence. + + + + + Do not break your sentence with lists. For example, do not structure + the phrase like this: + +You can use the following commands: -a -z -b to start the system update. - - Keep the sentence together instead: - + + Keep the sentence together instead: + + To start the system update, you can use the following commands: -a -z -b - - -
+ + +
diff --git a/xml/docu_styleguide.xmlformat.xml b/xml/docu_styleguide.xmlformat.xml index 655f169b..efd20deb 100644 --- a/xml/docu_styleguide.xmlformat.xml +++ b/xml/docu_styleguide.xmlformat.xml @@ -5,186 +5,189 @@ %entities; ]> - Formatting XML - - - This section provides information on formatting XML sources. - - - - - - Line ends: - - Lines should end with a Unix line end character (also called line feed, - LF, newline, or \n). - - - - - - Line length: - - Lines should be at most 100 characters long, unless one of the following - exceptions applies: - - - + Formatting XML + + This section provides information on formatting XML sources. + + - - Some computer output, computer input or URIs may run longer and cannot - be broken. - + + Line ends: + + Lines should end with a Unix line end character (also called line + feed, LF, newline, or \n). + + - - Some elements become much harder to read if broken. For example, that can - be the case for long menuchoice elements. - + + Line length: + + Lines should be at most 100 characters long, unless one of the + following exceptions applies: + + + + + + Some computer output, computer input or URIs may run longer and + cannot be broken. + + + + + Some elements become much harder to read if broken. For example, + that can be the case for long + menuchoice elements. + + + + + Aim to minimize the size of diffs in version control, to make + reading diffs more efficient and version control storage more + efficient. For example, if a typo fix introduces a line with 82 + characters, consider keeping the line at that length. Also, avoid + reflowing entire paragraphs of text, as that will also lead to + hard-to-read diffs. + + + - - Aim to minimize the size of diffs in version control, to make reading - diffs more efficient and version control storage more efficient. For - example, if a typo fix introduces a line with 82 characters, consider - keeping the line at that length. Also, avoid reflowing entire - paragraphs of text, as that will also lead to hard-to-read diffs. - + + Indentation: + + Indent using two space characters per indentation level. Make sure + your editor does not replace spaces with tabs. Documents should not + contain any tab characters. + + - - - - - Indentation: - - Indent using two space characters per indentation level. Make sure - your editor does not replace spaces with tabs. Documents should not - contain any tab characters. - - - - - - Trailing whitespace: - - Avoid introducing trailing whitespace characters such as spaces, - protected spaces or tabs. Many editors have an option to view such - characters. git diff will show newly introduced - trailing whitespace characters in red. - - - - - - Formatting of block elements: - - Block elements are all DocBook elements that create a rectangular visual - block in the layout, such as para, - table or figure. - Format block elements with new lines before and after each tag and make - sure they follow the indentation of the document: - - + + + Trailing whitespace: + + Avoid introducing trailing whitespace characters such as spaces, + protected spaces or tabs. Many editors have an option to view such + characters. git diff will show newly introduced + trailing whitespace characters in red. + + + + + + Formatting of block elements: + + Block elements are all DocBook elements that create a rectangular + visual block in the layout, such as para, + table or + figure. Format block elements with new + lines before and after each tag and make sure they follow the + indentation of the document: + + <block> Content of block, indented by a space. </block> - - For information about the usage of screen, see - . - - - - - Formatting of inline elements: - - Block elements are all DocBook elements that can be reflowed freely - within a block element, such as - emphasis, keycap, - or guimenu. Format inline elements along - with other inline content without adding newlines or extra indentation: - - + + For information about the usage of screen, + see . + + + + + Formatting of inline elements: + + Block elements are all DocBook elements that can be reflowed freely + within a block element, such as emphasis, + keycap, or + guimenu. Format inline elements along + with other inline content without adding newlines or extra + indentation: + + <block> Content of block <inline>content of inline</inline>. <block> - - - - Formatting of title elements: - - The title elements title and - term are block elements. However, they - provoke a style sheet quirk and should be treated differently. This - avoids superfluous whitespace when used in the context of a - cross-reference. Format title elements with new lines before the opening - tag and after the closing tag and make sure they follow the indentation - of the document: - - + + + + Formatting of title elements: + + The title elements title and + term are block elements. However, they + provoke a style sheet quirk and should be treated differently. This + avoids superfluous whitespace when used in the context of a + cross-reference. Format title elements with new lines before the + opening tag and after the closing tag and make sure they follow the + indentation of the document: + + <title>Content of Title</block> - - - - Formatting of computer output/computer input blocks: - - The Computer Output/Computer Input Block Element - screen should be treated like a block - element but multi-line screen elements - should not be indented to aid source reading flow and avoid the trap of - adding extraneous leading space to their content. (Single-line - screen can be indented). - - - - - - XML comments - - XML comments should follow the indentation of the document. Where - feasible, put XML comments on new lines to make reading diffs and later - removal of the comment easier: - - + + + + Formatting of computer output/computer input blocks: + + The Computer Output/Computer Input Block Element + screen should be treated like a block + element but multi-line screen elements + should not be indented to aid source reading flow and avoid the trap + of adding extraneous leading space to their content. (Single-line + screen can be indented). + + + + + + XML comments + + XML comments should follow the indentation of the document. Where + feasible, put XML comments on new lines to make reading diffs and + later removal of the comment easier: + + <block> Block content. <!-- An XML comment --> </block> - - XML comments must not contain the characters --. To - preserve such character combinations within comments, replace them with - -/-. - - - For information about the usage of XML comments, see - . - - - - - Reflowing entire files: - - Before reflowing entire files to a different XML formatting style, weigh - the cost of keeping the document in its current state against the cost - of reflowing. Reflowing often makes it easier to work with the document. - However, if the document has a rich editing history already, reflowing - makes it harder to properly use tools like git blame. - - - - - - - To easily convert documents to this style after importing them, use the - commands daps xmlformat (for an entire document) and - daps-xmlformat (for a single file). Note that while these - tools are very good otherwise, they do not reflow XML comments properly. - + + XML comments must not contain the characters --. To + preserve such character combinations within comments, replace them with + -/-. + + + For information about the usage of XML comments, see + . + + + + + Reflowing entire files: + + Before reflowing entire files to a different XML formatting style, + weigh the cost of keeping the document in its current state against + the cost of reflowing. Reflowing often makes it easier to work with + the document. However, if the document has a rich editing history + already, reflowing makes it harder to properly use tools like + git blame. + + + + + + To easily convert documents to this style after importing them, use the + commands daps xmlformat (for an entire document) and + daps-xmlformat (for a single file). Note that while + these tools are very good otherwise, they do not reflow XML comments + properly. + diff --git a/xml/entity-decl.ent b/xml/entity-decl.ent index c55d814c..18efe7fa 100644 --- a/xml/entity-decl.ent +++ b/xml/entity-decl.ent @@ -1,4 +1,4 @@ - + diff --git a/xml/gfdl.xml b/xml/gfdl.xml index ffece1d7..6d4fb0de 100644 --- a/xml/gfdl.xml +++ b/xml/gfdl.xml @@ -5,549 +5,549 @@ %entities; ]> - GNU Free Documentation License - - - Version 1.2, November 2002 - - - Copyright (C) 2000,2001,2002 Free Software Foundation, Inc. 59 Temple - Place, Suite 330, Boston, MA 02111-1307 USA - - - Everyone is permitted to copy and distribute verbatim copies of this - license document, but changing it is not allowed. - - - PREAMBLE - - - The purpose of this License is to make a manual, textbook, or other - functional and useful document “free” in the sense of - freedom: to assure everyone the effective freedom to copy and - redistribute it, with or without modifying it, either commercially or - noncommercially. Secondarily, this License preserves for the author and - publisher a way to get credit for their work, while not being considered - responsible for modifications made by others. - - - - This License is a kind of copyleft, which means that - derivative works of the document must themselves be free in the same - sense. It complements the GNU General Public License, which is a copyleft - license designed for free software. - - - - We have designed this License in order to use it for manuals for free - software, because free software needs free documentation: a free program - should come with manuals providing the same freedoms that the software - does. But this License is not limited to software manuals; it can be used - for any textual work, regardless of subject matter or whether it is - published as a printed book. We recommend this License principally for - works whose purpose is instruction or reference. - - - - APPLICABILITY AND DEFINITIONS - - - This License applies to any manual or other work, in any medium, that - contains a notice placed by the copyright holder saying it can be - distributed under the terms of this License. Such a notice grants a - world-wide, royalty-free license, unlimited in duration, to use that work - under the conditions stated herein. The Document, below, - refers to any such manual or work. Any member of the public is a - licensee, and is addressed as you. You accept the license - if you copy, modify or distribute the work in a way requiring permission - under copyright law. - - - - A Modified Version of the Document means any work - containing the Document or a portion of it, either copied verbatim, or - with modifications and/or translated into another language. - - - - A Secondary Section is a named appendix or a front-matter - section of the Document that deals exclusively with the relationship of - the publishers or authors of the Document to the Document’s - overall subject (or to related matters) and contains nothing that could - fall directly within that overall subject. (Thus, if the Document is in - part a textbook of mathematics, a Secondary Section may not explain any - mathematics.) The relationship could be a matter of historical connection - with the subject or with related matters, or of legal, commercial, - philosophical, ethical or political position regarding them. - - - - The Invariant Sections are certain Secondary Sections - whose titles are designated, as being those of Invariant Sections, in the - notice that says that the Document is released under this License. If a - section does not fit the above definition of Secondary then it is not - allowed to be designated as Invariant. The Document may contain zero - Invariant Sections. If the Document does not identify any Invariant - Sections then there are none. - - - - The Cover Texts are certain short passages of text that - are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that - says that the Document is released under this License. A Front-Cover Text - may be at most 5 words, and a Back-Cover Text may be at most 25 words. - - - - A Transparent copy of the Document means a - machine-readable copy, represented in a format whose specification is - available to the general public, that is suitable for revising the - document straightforwardly with generic text editors or (for images - composed of pixels) generic paint programs or (for drawings) some widely - available drawing editor, and that is suitable for input to text - formatters or for automatic translation to a variety of formats suitable - for input to text formatters. A copy made in an otherwise Transparent - file format whose markup, or absence of markup, has been arranged to - thwart or discourage subsequent modification by readers is not - Transparent. An image format is not Transparent if used for any - substantial amount of text. A copy that is not Transparent - is called Opaque. - - - - Examples of suitable formats for Transparent copies include plain ASCII - without markup, Texinfo input format, LaTeX input format, SGML or XML - using a publicly available DTD, and standard-conforming simple HTML, - PostScript or PDF designed for human modification. Examples of - transparent image formats include PNG, XCF and JPG. Opaque formats - include proprietary formats that can be read and edited only by - proprietary word processors, SGML or XML for which the DTD and/or - processing tools are not generally available, and the machine-generated - HTML, PostScript or PDF produced by some word processors for output - purposes only. - - - - The Title Page means, for a printed book, the title page - itself, plus such following pages as are needed to hold, legibly, the - material this License requires to appear in the title page. For works in - formats which do not have any title page as such, Title - Page means the text near the most prominent appearance of the - work’s title, preceding the beginning of the body of the text. - - - - A section Entitled XYZ means a named subunit of the - Document whose title either is precisely XYZ or contains XYZ in - parentheses following text that translates XYZ in another language. (Here - XYZ stands for a specific section name mentioned below, such as - Acknowledgements, Dedications, - Endorsements, or History.) To - Preserve the Title of such a section when you modify the - Document means that it remains a section Entitled XYZ - according to this definition. - - - - The Document may include Warranty Disclaimers next to the notice which - states that this License applies to the Document. These Warranty - Disclaimers are considered to be included by reference in this License, - but only as regards disclaiming warranties: any other implication that - these Warranty Disclaimers may have is void and has no effect on the - meaning of this License. - - - - VERBATIM COPYING - - - You may copy and distribute the Document in any medium, either - commercially or noncommercially, provided that this License, the - copyright notices, and the license notice saying this License applies to - the Document are reproduced in all copies, and that you add no other - conditions whatsoever to those of this License. You may not use technical - measures to obstruct or control the reading or further copying of the - copies you make or distribute. However, you may accept compensation in - exchange for copies. If you distribute a large enough number of copies - you must also follow the conditions in section 3. - - - - You may also lend copies, under the same conditions stated above, and you - may publicly display copies. - - - - COPYING IN QUANTITY - - - If you publish printed copies (or copies in media that commonly have - printed covers) of the Document, numbering more than 100, and the - Document’s license notice requires Cover Texts, you must enclose - the copies in covers that carry, clearly and legibly, all these Cover - Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the - back cover. Both covers must also clearly and legibly identify you as the - publisher of these copies. The front cover must present the full title - with all words of the title equally prominent and visible. You may add - other material on the covers in addition. Copying with changes limited to - the covers, as long as they preserve the title of the Document and - satisfy these conditions, can be treated as verbatim copying in other - respects. - - - - If the required texts for either cover are too voluminous to fit legibly, - you should put the first ones listed (as many as fit reasonably) on the - actual cover, and continue the rest onto adjacent pages. - - - - If you publish or distribute Opaque copies of the Document numbering more - than 100, you must either include a machine-readable Transparent copy - along with each Opaque copy, or state in or with each Opaque copy a - computer-network location from which the general network-using public has - access to download using public-standard network protocols a complete - Transparent copy of the Document, free of added material. If you use the - latter option, you must take reasonably prudent steps, when you begin - distribution of Opaque copies in quantity, to ensure that this - Transparent copy will remain thus accessible at the stated location until - at least one year after the last time you distribute an Opaque copy - (directly or through your agents or retailers) of that edition to the - public. - - - - It is requested, but not required, that you contact the authors of the - Document well before redistributing any large number of copies, to give - them a chance to provide you with an updated version of the Document. - - - - MODIFICATIONS - - - You may copy and distribute a Modified Version of the Document under the - conditions of sections 2 and 3 above, provided that you release the - Modified Version under precisely this License, with the Modified Version - filling the role of the Document, thus licensing distribution and - modification of the Modified Version to whoever possesses a copy of it. - In addition, you must do these things in the Modified Version: - - - - A. - - Use in the Title Page (and on the covers, if any) a title distinct from - that of the Document, and from those of previous versions (which should, - if there were any, be listed in the History section of the Document). - You may use the same title as a previous version if the original - publisher of that version gives permission. - - - - - B. - - List on the Title Page, as authors, one or more persons or entities - responsible for authorship of the modifications in the Modified Version, - together with at least five of the principal authors of the Document - (all of its principal authors, if it has fewer than five), unless they - release you from this requirement. - - - - - C. - - State on the Title page the name of the publisher of the Modified - Version, as the publisher. - - - - - D. - - Preserve all the copyright notices of the Document. - - - - - E. - - Add an appropriate copyright notice for your modifications adjacent to - the other copyright notices. - - - - - F. - - Include, immediately after the copyright notices, a license notice - giving the public permission to use the Modified Version under the terms - of this License, in the form shown in the Addendum below. - - - - - G. - - Preserve in that license notice the full lists of Invariant Sections and - required Cover Texts given in the Document’s license notice. - - - - - H. - - Include an unaltered copy of this License. - - - - - I. - - Preserve the section Entitled History, Preserve its - Title, and add to it an item stating at least the title, year, new - authors, and publisher of the Modified Version as given on the Title - Page. If there is no section Entitled History in the - Document, create one stating the title, year, authors, and publisher of - the Document as given on its Title Page, then add an item describing the - Modified Version as stated in the previous sentence. - - - - - J. - - Preserve the network location, if any, given in the Document for public - access to a Transparent copy of the Document, and likewise the network - locations given in the Document for previous versions it was based on. - These may be placed in the History section. You may omit - a network location for a work that was published at least four years - before the Document itself, or if the original publisher of the version - it refers to gives permission. - - - - - K. - - For any section Entitled Acknowledgements or - Dedications, Preserve the Title of the section, and - preserve in the section all the substance and tone of each of the - contributor acknowledgements and/or dedications given therein. - - - - - L. - - Preserve all the Invariant Sections of the Document, unaltered in their - text and in their titles. Section numbers or the equivalent are not - considered part of the section titles. - - - - - M. - - Delete any section Entitled Endorsements. Such a section - may not be included in the Modified Version. - - - - - N. - - Do not retitle any existing section to be Entitled - Endorsements or to conflict in title with any Invariant - Section. - - - - - O. - - Preserve any Warranty Disclaimers. - - - - - If the Modified Version includes new front-matter sections or appendices - that qualify as Secondary Sections and contain no material copied from - the Document, you may at your option designate some or all of these - sections as invariant. To do this, add their titles to the list of - Invariant Sections in the Modified Version’s license notice. - These titles must be distinct from any other section titles. - - - - You may add a section Entitled Endorsements, provided it - contains nothing but endorsements of your Modified Version by various - parties--for example, statements of peer review or that the text has been - approved by an organization as the authoritative definition of a - standard. - - - - You may add a passage of up to five words as a Front-Cover Text, and a - passage of up to 25 words as a Back-Cover Text, to the end of the list of - Cover Texts in the Modified Version. Only one passage of Front-Cover Text - and one of Back-Cover Text may be added by (or through arrangements made - by) any one entity. If the Document already includes a cover text for the - same cover, previously added by you or by arrangement made by the same - entity you are acting on behalf of, you may not add another; but you may - replace the old one, on explicit permission from the previous publisher - that added the old one. - - - - The author(s) and publisher(s) of the Document do not by this License - give permission to use their names for publicity for or to assert or - imply endorsement of any Modified Version. - - - - COMBINING DOCUMENTS - - - You may combine the Document with other documents released under this - License, under the terms defined in section 4 above for modified - versions, provided that you include in the combination all of the - Invariant Sections of all of the original documents, unmodified, and list - them all as Invariant Sections of your combined work in its license - notice, and that you preserve all their Warranty Disclaimers. - - - - The combined work need only contain one copy of this License, and - multiple identical Invariant Sections may be replaced with a single copy. - If there are multiple Invariant Sections with the same name but different - contents, make the title of each such section unique by adding at the end - of it, in parentheses, the name of the original author or publisher of - that section if known, or else a unique number. Make the same adjustment - to the section titles in the list of Invariant Sections in the license - notice of the combined work. - - - - In the combination, you must combine any sections Entitled - History in the various original documents, forming one - section Entitled History; likewise combine any sections - Entitled Acknowledgements, and any sections Entitled - Dedications. You must delete all sections Entitled - Endorsements. - - - - COLLECTIONS OF DOCUMENTS - - - You may make a collection consisting of the Document and other documents - released under this License, and replace the individual copies of this - License in the various documents with a single copy that is included in - the collection, provided that you follow the rules of this License for - verbatim copying of each of the documents in all other respects. - - - - You may extract a single document from such a collection, and distribute - it individually under this License, provided you insert a copy of this - License into the extracted document, and follow this License in all other - respects regarding verbatim copying of that document. - - - - AGGREGATION WITH INDEPENDENT WORKS - - - A compilation of the Document or its derivatives with other separate and - independent documents or works, in or on a volume of a storage or - distribution medium, is called an “aggregate” if the - copyright resulting from the compilation is not used to limit the legal - rights of the compilation’s users beyond what the individual - works permit. When the Document is included in an aggregate, this License - does not apply to the other works in the aggregate which are not - themselves derivative works of the Document. - - - - If the Cover Text requirement of section 3 is applicable to these copies - of the Document, then if the Document is less than one half of the entire - aggregate, the Document’s Cover Texts may be placed on covers - that bracket the Document within the aggregate, or the electronic - equivalent of covers if the Document is in electronic form. Otherwise - they must appear on printed covers that bracket the whole aggregate. - - - - TRANSLATION - - - Translation is considered a kind of modification, so you may distribute - translations of the Document under the terms of section 4. Replacing - Invariant Sections with translations requires special permission from - their copyright holders, but you may include translations of some or all - Invariant Sections in addition to the original versions of these - Invariant Sections. You may include a translation of this License, and - all the license notices in the Document, and any Warranty Disclaimers, - provided that you also include the original English version of this - License and the original versions of those notices and disclaimers. In - case of a disagreement between the translation and the original version - of this License or a notice or disclaimer, the original version will - prevail. - - - - If a section in the Document is Entitled Acknowledgements, - Dedications, or History, the requirement - (section 4) to Preserve its Title (section 1) will typically require - changing the actual title. - - - - TERMINATION - - - You may not copy, modify, sublicense, or distribute the Document except - as expressly provided for under this License. Any other attempt to copy, - modify, sublicense or distribute the Document is void, and will - automatically terminate your rights under this License. However, parties - who have received copies, or rights, from you under this License will not - have their licenses terminated so long as such parties remain in full - compliance. - - - - FUTURE REVISIONS OF THIS LICENSE - - - The Free Software Foundation may publish new, revised versions of the GNU - Free Documentation License from time to time. Such new versions will be - similar in spirit to the present version, but may differ in detail to - address new problems or concerns. See - http://www.gnu.org/copyleft/. - - - - Each version of the License is given a distinguishing version number. If - the Document specifies that a particular numbered version of this License - or any later version applies to it, you have the option of - following the terms and conditions either of that specified version or of - any later version that has been published (not as a draft) by the Free - Software Foundation. If the Document does not specify a version number of - this License, you may choose any version ever published (not as a draft) - by the Free Software Foundation. - - - - ADDENDUM: How to use this License for your documents - - - To use this License in a document you have written, include a copy of the - License in the document and put the following copyright and license - notices just after the title page: - + GNU Free Documentation License + + + Version 1.2, November 2002 + + + Copyright (C) 2000,2001,2002 Free Software Foundation, Inc. 59 Temple + Place, Suite 330, Boston, MA 02111-1307 USA + + + Everyone is permitted to copy and distribute verbatim copies of this + license document, but changing it is not allowed. + + + PREAMBLE + + + The purpose of this License is to make a manual, textbook, or other + functional and useful document “free” in the sense of + freedom: to assure everyone the effective freedom to copy and + redistribute it, with or without modifying it, either commercially or + noncommercially. Secondarily, this License preserves for the author and + publisher a way to get credit for their work, while not being considered + responsible for modifications made by others. + + + + This License is a kind of copyleft, which means that + derivative works of the document must themselves be free in the same + sense. It complements the GNU General Public License, which is a copyleft + license designed for free software. + + + + We have designed this License in order to use it for manuals for free + software, because free software needs free documentation: a free program + should come with manuals providing the same freedoms that the software + does. But this License is not limited to software manuals; it can be used + for any textual work, regardless of subject matter or whether it is + published as a printed book. We recommend this License principally for + works whose purpose is instruction or reference. + + + + APPLICABILITY AND DEFINITIONS + + + This License applies to any manual or other work, in any medium, that + contains a notice placed by the copyright holder saying it can be + distributed under the terms of this License. Such a notice grants a + world-wide, royalty-free license, unlimited in duration, to use that work + under the conditions stated herein. The Document, below, + refers to any such manual or work. Any member of the public is a + licensee, and is addressed as you. You accept the license + if you copy, modify or distribute the work in a way requiring permission + under copyright law. + + + + A Modified Version of the Document means any work + containing the Document or a portion of it, either copied verbatim, or + with modifications and/or translated into another language. + + + + A Secondary Section is a named appendix or a front-matter + section of the Document that deals exclusively with the relationship of + the publishers or authors of the Document to the Document’s overall + subject (or to related matters) and contains nothing that could fall + directly within that overall subject. (Thus, if the Document is in part a + textbook of mathematics, a Secondary Section may not explain any + mathematics.) The relationship could be a matter of historical connection + with the subject or with related matters, or of legal, commercial, + philosophical, ethical or political position regarding them. + + + + The Invariant Sections are certain Secondary Sections + whose titles are designated, as being those of Invariant Sections, in the + notice that says that the Document is released under this License. If a + section does not fit the above definition of Secondary then it is not + allowed to be designated as Invariant. The Document may contain zero + Invariant Sections. If the Document does not identify any Invariant + Sections then there are none. + + + + The Cover Texts are certain short passages of text that + are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that + says that the Document is released under this License. A Front-Cover Text + may be at most 5 words, and a Back-Cover Text may be at most 25 words. + + + + A Transparent copy of the Document means a + machine-readable copy, represented in a format whose specification is + available to the general public, that is suitable for revising the + document straightforwardly with generic text editors or (for images + composed of pixels) generic paint programs or (for drawings) some widely + available drawing editor, and that is suitable for input to text + formatters or for automatic translation to a variety of formats suitable + for input to text formatters. A copy made in an otherwise Transparent + file format whose markup, or absence of markup, has been arranged to + thwart or discourage subsequent modification by readers is not + Transparent. An image format is not Transparent if used for any + substantial amount of text. A copy that is not Transparent + is called Opaque. + + + + Examples of suitable formats for Transparent copies include plain ASCII + without markup, Texinfo input format, LaTeX input format, SGML or XML + using a publicly available DTD, and standard-conforming simple HTML, + PostScript or PDF designed for human modification. Examples of + transparent image formats include PNG, XCF and JPG. Opaque formats + include proprietary formats that can be read and edited only by + proprietary word processors, SGML or XML for which the DTD and/or + processing tools are not generally available, and the machine-generated + HTML, PostScript or PDF produced by some word processors for output + purposes only. + + + + The Title Page means, for a printed book, the title page + itself, plus such following pages as are needed to hold, legibly, the + material this License requires to appear in the title page. For works in + formats which do not have any title page as such, Title + Page means the text near the most prominent appearance of the + work’s title, preceding the beginning of the body of the text. + + + + A section Entitled XYZ means a named subunit of the + Document whose title either is precisely XYZ or contains XYZ in + parentheses following text that translates XYZ in another language. (Here + XYZ stands for a specific section name mentioned below, such as + Acknowledgements, Dedications, + Endorsements, or History.) To + Preserve the Title of such a section when you modify the + Document means that it remains a section Entitled XYZ + according to this definition. + + + + The Document may include Warranty Disclaimers next to the notice which + states that this License applies to the Document. These Warranty + Disclaimers are considered to be included by reference in this License, + but only as regards disclaiming warranties: any other implication that + these Warranty Disclaimers may have is void and has no effect on the + meaning of this License. + + + + VERBATIM COPYING + + + You may copy and distribute the Document in any medium, either + commercially or noncommercially, provided that this License, the + copyright notices, and the license notice saying this License applies to + the Document are reproduced in all copies, and that you add no other + conditions whatsoever to those of this License. You may not use technical + measures to obstruct or control the reading or further copying of the + copies you make or distribute. However, you may accept compensation in + exchange for copies. If you distribute a large enough number of copies + you must also follow the conditions in section 3. + + + + You may also lend copies, under the same conditions stated above, and you + may publicly display copies. + + + + COPYING IN QUANTITY + + + If you publish printed copies (or copies in media that commonly have + printed covers) of the Document, numbering more than 100, and the + Document’s license notice requires Cover Texts, you must enclose + the copies in covers that carry, clearly and legibly, all these Cover + Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the + back cover. Both covers must also clearly and legibly identify you as the + publisher of these copies. The front cover must present the full title + with all words of the title equally prominent and visible. You may add + other material on the covers in addition. Copying with changes limited to + the covers, as long as they preserve the title of the Document and + satisfy these conditions, can be treated as verbatim copying in other + respects. + + + + If the required texts for either cover are too voluminous to fit legibly, + you should put the first ones listed (as many as fit reasonably) on the + actual cover, and continue the rest onto adjacent pages. + + + + If you publish or distribute Opaque copies of the Document numbering more + than 100, you must either include a machine-readable Transparent copy + along with each Opaque copy, or state in or with each Opaque copy a + computer-network location from which the general network-using public has + access to download using public-standard network protocols a complete + Transparent copy of the Document, free of added material. If you use the + latter option, you must take reasonably prudent steps, when you begin + distribution of Opaque copies in quantity, to ensure that this + Transparent copy will remain thus accessible at the stated location until + at least one year after the last time you distribute an Opaque copy + (directly or through your agents or retailers) of that edition to the + public. + + + + It is requested, but not required, that you contact the authors of the + Document well before redistributing any large number of copies, to give + them a chance to provide you with an updated version of the Document. + + + + MODIFICATIONS + + + You may copy and distribute a Modified Version of the Document under the + conditions of sections 2 and 3 above, provided that you release the + Modified Version under precisely this License, with the Modified Version + filling the role of the Document, thus licensing distribution and + modification of the Modified Version to whoever possesses a copy of it. + In addition, you must do these things in the Modified Version: + + + + A. + + Use in the Title Page (and on the covers, if any) a title distinct from + that of the Document, and from those of previous versions (which + should, if there were any, be listed in the History section of the + Document). You may use the same title as a previous version if the + original publisher of that version gives permission. + + + + + B. + + List on the Title Page, as authors, one or more persons or entities + responsible for authorship of the modifications in the Modified + Version, together with at least five of the principal authors of the + Document (all of its principal authors, if it has fewer than five), + unless they release you from this requirement. + + + + + C. + + State on the Title page the name of the publisher of the Modified + Version, as the publisher. + + + + + D. + + Preserve all the copyright notices of the Document. + + + + + E. + + Add an appropriate copyright notice for your modifications adjacent to + the other copyright notices. + + + + + F. + + Include, immediately after the copyright notices, a license notice + giving the public permission to use the Modified Version under the + terms of this License, in the form shown in the Addendum below. + + + + + G. + + Preserve in that license notice the full lists of Invariant Sections + and required Cover Texts given in the Document’s license notice. + + + + + H. + + Include an unaltered copy of this License. + + + + + I. + + Preserve the section Entitled History, Preserve its + Title, and add to it an item stating at least the title, year, new + authors, and publisher of the Modified Version as given on the Title + Page. If there is no section Entitled History in the + Document, create one stating the title, year, authors, and publisher of + the Document as given on its Title Page, then add an item describing + the Modified Version as stated in the previous sentence. + + + + + J. + + Preserve the network location, if any, given in the Document for public + access to a Transparent copy of the Document, and likewise the network + locations given in the Document for previous versions it was based on. + These may be placed in the History section. You may omit + a network location for a work that was published at least four years + before the Document itself, or if the original publisher of the version + it refers to gives permission. + + + + + K. + + For any section Entitled Acknowledgements or + Dedications, Preserve the Title of the section, and + preserve in the section all the substance and tone of each of the + contributor acknowledgements and/or dedications given therein. + + + + + L. + + Preserve all the Invariant Sections of the Document, unaltered in their + text and in their titles. Section numbers or the equivalent are not + considered part of the section titles. + + + + + M. + + Delete any section Entitled Endorsements. Such a section + may not be included in the Modified Version. + + + + + N. + + Do not retitle any existing section to be Entitled + Endorsements or to conflict in title with any Invariant + Section. + + + + + O. + + Preserve any Warranty Disclaimers. + + + + + If the Modified Version includes new front-matter sections or appendices + that qualify as Secondary Sections and contain no material copied from + the Document, you may at your option designate some or all of these + sections as invariant. To do this, add their titles to the list of + Invariant Sections in the Modified Version’s license notice. These + titles must be distinct from any other section titles. + + + + You may add a section Entitled Endorsements, provided it + contains nothing but endorsements of your Modified Version by various + parties--for example, statements of peer review or that the text has been + approved by an organization as the authoritative definition of a + standard. + + + + You may add a passage of up to five words as a Front-Cover Text, and a + passage of up to 25 words as a Back-Cover Text, to the end of the list of + Cover Texts in the Modified Version. Only one passage of Front-Cover Text + and one of Back-Cover Text may be added by (or through arrangements made + by) any one entity. If the Document already includes a cover text for the + same cover, previously added by you or by arrangement made by the same + entity you are acting on behalf of, you may not add another; but you may + replace the old one, on explicit permission from the previous publisher + that added the old one. + + + + The author(s) and publisher(s) of the Document do not by this License + give permission to use their names for publicity for or to assert or + imply endorsement of any Modified Version. + + + + COMBINING DOCUMENTS + + + You may combine the Document with other documents released under this + License, under the terms defined in section 4 above for modified + versions, provided that you include in the combination all of the + Invariant Sections of all of the original documents, unmodified, and list + them all as Invariant Sections of your combined work in its license + notice, and that you preserve all their Warranty Disclaimers. + + + + The combined work need only contain one copy of this License, and + multiple identical Invariant Sections may be replaced with a single copy. + If there are multiple Invariant Sections with the same name but different + contents, make the title of each such section unique by adding at the end + of it, in parentheses, the name of the original author or publisher of + that section if known, or else a unique number. Make the same adjustment + to the section titles in the list of Invariant Sections in the license + notice of the combined work. + + + + In the combination, you must combine any sections Entitled + History in the various original documents, forming one + section Entitled History; likewise combine any sections + Entitled Acknowledgements, and any sections Entitled + Dedications. You must delete all sections Entitled + Endorsements. + + + + COLLECTIONS OF DOCUMENTS + + + You may make a collection consisting of the Document and other documents + released under this License, and replace the individual copies of this + License in the various documents with a single copy that is included in + the collection, provided that you follow the rules of this License for + verbatim copying of each of the documents in all other respects. + + + + You may extract a single document from such a collection, and distribute + it individually under this License, provided you insert a copy of this + License into the extracted document, and follow this License in all other + respects regarding verbatim copying of that document. + + + + AGGREGATION WITH INDEPENDENT WORKS + + + A compilation of the Document or its derivatives with other separate and + independent documents or works, in or on a volume of a storage or + distribution medium, is called an “aggregate” if the + copyright resulting from the compilation is not used to limit the legal + rights of the compilation’s users beyond what the individual works + permit. When the Document is included in an aggregate, this License does + not apply to the other works in the aggregate which are not themselves + derivative works of the Document. + + + + If the Cover Text requirement of section 3 is applicable to these copies + of the Document, then if the Document is less than one half of the entire + aggregate, the Document’s Cover Texts may be placed on covers that + bracket the Document within the aggregate, or the electronic equivalent + of covers if the Document is in electronic form. Otherwise they must + appear on printed covers that bracket the whole aggregate. + + + + TRANSLATION + + + Translation is considered a kind of modification, so you may distribute + translations of the Document under the terms of section 4. Replacing + Invariant Sections with translations requires special permission from + their copyright holders, but you may include translations of some or all + Invariant Sections in addition to the original versions of these + Invariant Sections. You may include a translation of this License, and + all the license notices in the Document, and any Warranty Disclaimers, + provided that you also include the original English version of this + License and the original versions of those notices and disclaimers. In + case of a disagreement between the translation and the original version + of this License or a notice or disclaimer, the original version will + prevail. + + + + If a section in the Document is Entitled Acknowledgements, + Dedications, or History, the requirement + (section 4) to Preserve its Title (section 1) will typically require + changing the actual title. + + + + TERMINATION + + + You may not copy, modify, sublicense, or distribute the Document except + as expressly provided for under this License. Any other attempt to copy, + modify, sublicense or distribute the Document is void, and will + automatically terminate your rights under this License. However, parties + who have received copies, or rights, from you under this License will not + have their licenses terminated so long as such parties remain in full + compliance. + + + + FUTURE REVISIONS OF THIS LICENSE + + + The Free Software Foundation may publish new, revised versions of the GNU + Free Documentation License from time to time. Such new versions will be + similar in spirit to the present version, but may differ in detail to + address new problems or concerns. See + http://www.gnu.org/copyleft/. + + + + Each version of the License is given a distinguishing version number. If + the Document specifies that a particular numbered version of this License + or any later version applies to it, you have the option of + following the terms and conditions either of that specified version or of + any later version that has been published (not as a draft) by the Free + Software Foundation. If the Document does not specify a version number of + this License, you may choose any version ever published (not as a draft) + by the Free Software Foundation. + + + + ADDENDUM: How to use this License for your documents + + + To use this License in a document you have written, include a copy of the + License in the document and put the following copyright and license + notices just after the title page: + Copyright (c) YEAR YOUR NAME. @@ -559,27 +559,27 @@ A copy of the license is included in the section entitled “GNU Free Documentation License”. - - If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, - replace the “with...Texts.” line with this: - + + If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, + replace the “with...Texts.” line with this: + with the Invariant Sections being LIST THEIR TITLES, with the Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. - - If you have Invariant Sections without Cover Texts, or some other - combination of the three, merge those two alternatives to suit the - situation. - - - - If your document contains nontrivial examples of program code, we - recommend releasing these examples in parallel under your choice of free - software license, such as the GNU General Public License, to permit their - use in free software. - - + + If you have Invariant Sections without Cover Texts, or some other + combination of the three, merge those two alternatives to suit the + situation. + + + + If your document contains nontrivial examples of program code, we + recommend releasing these examples in parallel under your choice of free + software license, such as the GNU General Public License, to permit their + use in free software. + + diff --git a/xml/legal_suse+gfdl.xml b/xml/legal_suse+gfdl.xml index b41261d7..5622b1cf 100644 --- a/xml/legal_suse+gfdl.xml +++ b/xml/legal_suse+gfdl.xml @@ -5,29 +5,29 @@ %entities; ]> - - Copyright © 2007– - SUSE LLC and contributors. All rights reserved. - - - Permission is granted to copy, distribute and/or modify this document - under the terms of the GNU Free Documentation License, Version 1.2 or (at - your option) version 1.3; with the Invariant Section being this copyright - notice and license. A copy of the license version 1.2 is included in the - section entitled GNU Free Documentation License. - - - For &suse; trademarks, see - . - All other third-party trademarks are the property of their respective - owners. Trademark symbols (®, ™ etc.) denote trademarks - of &suse; and its affiliates. Asterisks (*) denote third-party - trademarks. - - - All information found in this book has been compiled with utmost attention - to detail. However, this does not guarantee complete accuracy. Neither - SUSE LLC, its affiliates, the authors nor the translators shall be held - liable for possible errors or the consequences thereof. - + + Copyright © 2007– + + SUSE LLC and contributors. All rights reserved. + + + Permission is granted to copy, distribute and/or modify this document under + the terms of the GNU Free Documentation License, Version 1.2 or (at your + option) version 1.3; with the Invariant Section being this copyright notice + and license. A copy of the license version 1.2 is included in the section + entitled GNU Free Documentation License. + + + For &suse; trademarks, see + . All other + third-party trademarks are the property of their respective owners. + Trademark symbols (®, ™ etc.) denote trademarks of &suse; and its + affiliates. Asterisks (*) denote third-party trademarks. + + + All information found in this book has been compiled with utmost attention + to detail. However, this does not guarantee complete accuracy. Neither SUSE + LLC, its affiliates, the authors nor the translators shall be held liable + for possible errors or the consequences thereof. +