From fe586291ff3c9155fa1967bf60e56db449d6a165 Mon Sep 17 00:00:00 2001 From: Andreas Jaeger Date: Mon, 2 May 2016 14:29:59 +0200 Subject: [PATCH] Remove openstack-doc-test openstack-doc-test is used for building of DocBook XML files. For index page generation openstack-indexpage can be used. Remove openstack-doc-test together with all support files. Change-Id: I5589bc634e1f630f79b3d6e8bffee939c5300bf2 --- HACKING.rst | 10 +- README.rst | 52 - doc/source/conf.py | 6 +- os_doc_tools/doctest.py | 1586 -- os_doc_tools/openstack/__init__.py | 0 os_doc_tools/openstack/common/__init__.py | 17 - os_doc_tools/openstack/common/gettextutils.py | 479 - os_doc_tools/openstack/common/importutils.py | 73 - os_doc_tools/openstack/common/jsonutils.py | 190 - os_doc_tools/openstack/common/local.py | 45 - os_doc_tools/openstack/common/log.py | 703 - os_doc_tools/openstack/common/strutils.py | 295 - os_doc_tools/openstack/common/timeutils.py | 210 - os_doc_tools/resources/README.rst | 8 - os_doc_tools/resources/docbookxi.rng | 18590 ---------------- os_doc_tools/resources/extensions.rng | 123 - os_doc_tools/resources/rackbook.rng | 558 - os_doc_tools/resources/wadl.rng | 414 - os_doc_tools/resources/wadl.xsd | 263 - os_doc_tools/resources/xml.xsd | 287 - .../docbook-removal-0c0d6c5a7b73ab77.yaml | 6 + setup.cfg | 1 - 22 files changed, 12 insertions(+), 23904 deletions(-) delete mode 100755 os_doc_tools/doctest.py delete mode 100644 os_doc_tools/openstack/__init__.py delete mode 100644 os_doc_tools/openstack/common/__init__.py delete mode 100644 os_doc_tools/openstack/common/gettextutils.py delete mode 100644 os_doc_tools/openstack/common/importutils.py delete mode 100644 os_doc_tools/openstack/common/jsonutils.py delete mode 100644 os_doc_tools/openstack/common/local.py delete mode 100644 os_doc_tools/openstack/common/log.py delete mode 100644 os_doc_tools/openstack/common/strutils.py delete mode 100644 os_doc_tools/openstack/common/timeutils.py delete mode 100644 os_doc_tools/resources/README.rst delete mode 100644 os_doc_tools/resources/docbookxi.rng delete mode 100644 os_doc_tools/resources/extensions.rng delete mode 100644 os_doc_tools/resources/rackbook.rng delete mode 100644 os_doc_tools/resources/wadl.rng delete mode 100644 os_doc_tools/resources/wadl.xsd delete mode 100644 os_doc_tools/resources/xml.xsd create mode 100644 releasenotes/notes/docbook-removal-0c0d6c5a7b73ab77.yaml diff --git a/HACKING.rst b/HACKING.rst index 9db75cb8..877ddcbf 100644 --- a/HACKING.rst +++ b/HACKING.rst @@ -12,15 +12,15 @@ Running tests So far there are no tests included with the package but a test suite would be welcome! -Since the openstack-doc-test tool is used for gating of the OpenStack +The openstack-indexpage tool is used while building the OpenStack documentation repositories, test building of these repositories with any changes done here. Testing can be done with simply a local install of -openstack-doc-tools, then checking out the gated repositories and +openstack-doc-tools, then checking out the repositories and running: ``tox`` inside of each. -The repositories gated by openstack-doc-tools are: -* api-guide +The repositories using openstack-doc-tools include: +* api-site * openstack-manuals -* operations-guide +* security-doc diff --git a/README.rst b/README.rst index c2d9aa8c..83a79482 100644 --- a/README.rst +++ b/README.rst @@ -9,16 +9,6 @@ For more details, see the `OpenStack Documentation wiki page Prerequisites ============= -`Apache Maven `_ must be installed to build the -documentation. - -To install Maven 3 for Ubuntu 12.04 and later, and Debian wheezy and later:: - - apt-get install maven - -On Fedora:: - - yum install maven You need to have Python 2.7 installed for using the tools. @@ -58,48 +48,6 @@ On Ubuntu:: apt-get install libxml2-dev libxslt-dev -Updating RNG schema files -========================= - -The repository contains in the directory ``os_doc_tools/resources`` a -local copy of some RNG schema files so that they do not need to be -downloaded each time for validation of XML and WADL files. - -Please see the ``README.txt`` in the directory for details on where -these files come from. - -Publishing of books -=================== -If you run the ``openstack-doc-test --check-build``, it will copy all -the books to the directory ``publish-docs`` in the top-level directory -of your repository. - -By default, it outputs a directory with the same name as the directory -where the pom.xml file lives in, such as glossary. You can -also check the output of the build job for the name. - -Some books need special treatment and there are three options you can -set in the file ``doc-test.conf``: - - * ``book`` - the name of a book that needs special treatment - * ``target_dir`` - the path of subdirectory starting at ``target`` - that is the root for publishing - * ``publish_dir`` - a new name to publish a book under - -As an example, to publish the compute-api version 2 in the directory -``publish-docs/api/openstack-compute/2``, use:: - - book = openstack-compute-api-2 - target_dir = target/docbkx/webhelp/api/openstack-compute/2 - publish_dir = api/openstack-compute/2 - -Note that these options can be specified multiple times and should -always be used this way. You do not need to set ``publish_dir`` but if -you set it, you need to use it every time. - -Also note that these are optional settings, the logic in the tool is -sufficient for many of the books. - * License: Apache License, Version 2.0 * Source: http://git.openstack.org/cgit/openstack/openstack-doc-tools * Bugs: http://bugs.launchpad.net/openstack-manuals diff --git a/doc/source/conf.py b/doc/source/conf.py index fe666ad0..ce035dfb 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -77,11 +77,7 @@ latex_documents = [ # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). -man_pages = [ - ('man/openstack-doc-test', 'openstack-doc-test', - u'OpenStack documentation tools', - [u'OpenStack'], 1) -] +man_pages = [] # If true, show URL addresses after external links. # man_show_urls = False diff --git a/os_doc_tools/doctest.py b/os_doc_tools/doctest.py deleted file mode 100755 index 957e36bc..00000000 --- a/os_doc_tools/doctest.py +++ /dev/null @@ -1,1586 +0,0 @@ -#!/usr/bin/env python - -# Licensed under the Apache License, Version 2.0 (the "License"); you may -# not use this file except in compliance with the License. You may obtain -# a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT -# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the -# License for the specific language governing permissions and limitations -# under the License. - -''' -Usage: - test.py [path] - -Validates all xml files against the DocBook 5 RELAX NG schema, and -attempts to build all books. - -Options: - path Root directory, defaults to /doc - -Ignores pom.xml files and subdirectories named "target". - -Requires: - - Python 2.7 or greater - - lxml Python library - - Maven -''' - -import gzip -import multiprocessing -import operator -import os -import re -import shutil -import subprocess -import sys -import time - -from six.moves.urllib import error as urlerr -from six.moves.urllib import request as urlreq - -from lxml import etree -from oslo_config import cfg - -import os_doc_tools -from os_doc_tools import index -from os_doc_tools import jsoncheck -from os_doc_tools.openstack.common import log - - -LOG = log.getLogger('openstack-doc-test') - -# These are files that are known to not pass syntax or niceness checks -# Add values via --file-exceptions. -FILE_EXCEPTIONS = [] - -# These are files that are known to not be in DocBook XML format. -# Add values via --build-file-exceptions. -BUILD_FILE_EXCEPTIONS = [] - -# These are books that we aren't checking yet. -BOOK_EXCEPTIONS = [] - -# These URLs will not be checked for reachability. Add values via -# --url-exception. -URL_EXCEPTIONS = [] - -# Mappings from books to build directories under target -BOOK_MAPPINGS = {} - -# Mappings from books to publish directories -BOOK_PUBLISH_MAPPINGS = {} - -RESULTS_OF_BUILDS = [] - -# List of recognized (allowable) os profiling directives. -KNOWN_OS_VALUES = ["debian", - "centos", - "fedora", - "opensuse", - "rhel", - "sles", - "ubuntu"] - - -# List of recognized (allowable) audience profiling directives. -KNOWN_AUDIENCE_VALUES = ["enduser", - "adminuser", - "installer", - "webpage"] - -OS_DOC_TOOLS_DIR = os.path.dirname(__file__) -# NOTE(jaegerandi): BASE_RNG needs to end with '/', otherwise -# the etree.parse call in get_wadl_schema will fail. -BASE_RNG = os.path.join(OS_DOC_TOOLS_DIR, 'resources/') -RACKBOOK_RNG = os.path.join(BASE_RNG, 'rackbook.rng') -DOCBOOKXI_RNG = os.path.join(BASE_RNG, 'docbookxi.rng') -WADL_RNG = os.path.join(BASE_RNG, 'wadl.rng') -WADL_XSD = os.path.join(BASE_RNG, 'wadl.xsd') - -SCRIPTS_DIR = os.path.join(OS_DOC_TOOLS_DIR, 'scripts') - - -def get_schema(is_api_site=False): - """Return the DocBook RELAX NG schema.""" - if is_api_site: - url = RACKBOOK_RNG - else: - url = DOCBOOKXI_RNG - relaxng_doc = etree.parse(url) - return etree.RelaxNG(relaxng_doc) - - -def get_wadl_schema(): - """Return the Wadl schema.""" - # NOTE(jaegerandi): We could use the RelaxNG instead - # like follows but this gives quite some errors at the - # moment, so only validate using the XMLSchema - # url = WADL_RNG - # relaxng_doc = etree.parse(url, base_url=BASE_RNG) - # return etree.RelaxNG(relaxng_doc) - url = WADL_XSD - schema = etree.parse(url, base_url=BASE_RNG) - return etree.XMLSchema(schema) - - -def validation_failed(schema, doc): - """Return True if the parsed doc fails against the schema. - - This will ignore validation failures of the type: IDREF attribute linkend - references an unknown ID. This is because we are validating individual - files that are being imported, and sometimes the reference isn't present - in the current file. - """ - return (not schema.validate(doc) and - any(log.type_name != "DTD_UNKNOWN_ID" for log in schema.error_log)) - - -def verify_section_tags_have_xmlid(doc): - """Check that all section tags have an xml:id attribute. - - Will throw an exception if there's at least one missing. - """ - ns = {"docbook": "http://docbook.org/ns/docbook"} - for node in doc.xpath('//docbook:section', namespaces=ns): - if "{http://www.w3.org/XML/1998/namespace}id" not in node.attrib: - raise ValueError("section missing xml:id attribute, line %d" % - node.sourceline) - - -def verify_attribute_profiling(doc, attribute, known_values): - """Check for conflicts in attribute profiling. - - Check for elements with attribute profiling set that conflicts with - the attribute profiling of nodes below them in the DOM - tree. This picks up cases where content is accidentally - omitted via conflicting profiling. Checks known_values also for - supported profiling values. - """ - - msg = [] - ns = {"docbook": "http://docbook.org/ns/docbook"} - path = '//docbook:*[@%s]' % attribute - for parent in doc.xpath(path, namespaces=ns): - p_tag = parent.tag - p_line = parent.sourceline - p_att_list = parent.attrib[attribute].split(';') - - for att in p_att_list: - if att not in known_values: - msg.append( - "'%s' is not a recognized %s profile on line %d." % - (att, attribute, p_line)) - - cpath = './/docbook:*[@%s]' % attribute - for child in parent.xpath(cpath, namespaces=ns): - c_tag = child.tag - c_line = child.sourceline - c_att_list = child.attrib[attribute].split(';') - for att in c_att_list: - if att not in p_att_list: - len_ns = len("{http://docbook.org/ns/docbook}") - msg.append( - "%s %s profiling (%s) conflicts with %s " - "profiling of %s on line %d." % - (p_tag[len_ns:], attribute, p_att_list, - attribute, c_tag[len_ns:], c_line)) - if msg: - raise ValueError("\n ".join(msg)) - - -def verify_profiling(doc): - """"Check profiling information.""" - verify_attribute_profiling(doc, "os", KNOWN_OS_VALUES) - verify_attribute_profiling(doc, "audience", KNOWN_AUDIENCE_VALUES) - - -def verify_newline_end_of_file(docfile): - """Check that there is a newline at the end of file.""" - - with open(docfile, 'r') as fp: - lines = fp.readlines() - lastline = lines[-1] - - if not lastline.endswith('\n'): - raise ValueError('last line of a file must end with a \\n') - - -def verify_unicode_niceness(docfile): - """Check that no unwanted unicode charaters are used.""" - - invalid_characters = '“”‘’―—' - - affected_lines = [] - lc = 0 - for line in open(docfile, 'r'): - lc += 1 - any(c in line for c in invalid_characters) - - if affected_lines: - raise ValueError("unwanted unicode charaters (one of %s) " - "found in line(s): %" % (" ".join(invalid_characters), - ", ".join(affected_lines))) - - -def verify_whitespace_niceness(docfile): - """Check that no unnecessary whitespaces are used.""" - checks = [ - re.compile(".*\s+\n$"), - ] - - elements = [ - 'listitem', - 'para', - 'td', - 'th', - 'command', - 'literal', - 'title', - 'caption', - 'filename', - 'userinput', - 'programlisting' - ] - - for element in elements: - checks.append(re.compile(".*<%s>\s+[\w\-().:!?{}\[\]]+.*\n" - % element)) - checks.append(re.compile(".*[\w\-().:!?{}\[\]]+\s+<\/%s>.*\n" - % element)) - - lc = 0 - affected_lines = [] - tab_lines = [] - nbsp_lines = [] - for line in open(docfile, 'r'): - lc = lc + 1 - if '\t' in line: - tab_lines.append(str(lc)) - - if '\xc2\xa0' in line: - nbsp_lines.append(str(lc)) - for check in checks: - if check.match(line) and lc not in affected_lines: - affected_lines.append(str(lc)) - - msg = "" - if nbsp_lines: - msg = "non-breaking space found in lines (use  ): %s" % ( - ", ".join(nbsp_lines)) - if affected_lines: - if (msg): - msg += "\n " - msg += ("trailing or unnecessary whitespaces found in lines: %s" - % (", ".join(affected_lines))) - if tab_lines: - if (msg): - msg += "\n " - msg += "tabs found in lines: %s" % ", ".join(tab_lines) - - if msg: - raise ValueError(msg) - - -def verify_valid_links(doc): - """Check that all linked URLs are reachable - - Will throw an exception if there's at least one unreachable URL. - """ - ns = {"docbook": "http://docbook.org/ns/docbook", - 'xlink': 'http://www.w3.org/1999/xlink'} - msg = [] - for node in doc.xpath('//docbook:link', namespaces=ns): - try: - url = node.attrib['{http://www.w3.org/1999/xlink}href'] - except Exception: - continue - - if url in URL_EXCEPTIONS: - continue - - try: - urlreq.urlopen(url) - except urlerr.HTTPError as e: - # Ignore some error codes: - # 403 (Forbidden) since it often means that the user-agent - # is wrong. - # 503 (Service Temporarily Unavailable) - if e.code not in [403, 503]: - e_line = node.sourceline - msg.append("URL %s not reachable at line %d, error %s" % ( - url, e_line, e)) - except urlerr.URLError as e: - e_line = node.sourceline - msg.append("URL %s invalid at line %d, error %s" % ( - url, e_line, e)) - - if msg: - raise ValueError("\n ".join(msg)) - - -def error_message(error_log): - """Return a string that contains the error message. - - We use this to filter out false positives related to IDREF attributes - """ - errs = [str(x) for x in error_log if x.type_name != 'DTD_UNKNOWN_ID'] - - # Reverse output so that earliest failures are reported first - errs.reverse() - return "\n".join(errs) - - -def www_touched(): - """Check whether files in www directory are touched.""" - - try: - git_args = ["git", "diff", "--name-only", "HEAD~1", "HEAD"] - modified_files = subprocess.check_output( - git_args, - universal_newlines=True).strip().split() - except (subprocess.CalledProcessError, OSError) as e: - print("git failed: %s" % e) - sys.exit(1) - - www_changed = False - other_changed = False - for f in modified_files: - if f.startswith("www/"): - www_changed = True - else: - other_changed = True - - return www_changed and not other_changed - - -def only_po_touched(): - """Check whether only files in locale directory are touched.""" - - try: - git_args = ["git", "diff", "--name-only", "HEAD~1", "HEAD"] - modified_files = subprocess.check_output( - git_args, - universal_newlines=True).strip().split() - except (subprocess.CalledProcessError, OSError) as e: - print("git failed: %s" % e) - sys.exit(1) - - locale_changed = False - other_changed = False - for f in modified_files: - if "/locale/" in f and f.endswith((".po", ".pot")): - locale_changed = True - else: - other_changed = True - - return locale_changed and not other_changed - - -def only_rst_touched(): - """Check whether only RST files are touched.""" - - try: - git_args = ["git", "diff", "--name-only", "HEAD~1", "HEAD"] - modified_files = subprocess.check_output( - git_args, - universal_newlines=True).strip().split() - except (subprocess.CalledProcessError, OSError) as e: - print("git failed: %s" % e) - sys.exit(1) - - rst_changed = False - other_changed = False - for f in modified_files: - if f.endswith(".rst"): - rst_changed = True - else: - other_changed = True - - return rst_changed and not other_changed - - -def check_modified_affects_all(rootdir): - """Check whether special files were modified. - - There are some special files where we should rebuild all books - if either of these is touched. - """ - - os.chdir(rootdir) - - try: - git_args = ["git", "diff", "--name-only", "HEAD~1", "HEAD"] - modified_files = subprocess.check_output( - git_args, - universal_newlines=True).strip().split() - except (subprocess.CalledProcessError, OSError) as e: - print("git failed: %s" % e) - sys.exit(1) - - special_files = [ - # Top-Level pom.xml - "pom.xml", - # doc/pom.xml in openstack-manuals - "doc/pom.xml" - ] - - for f in modified_files: - if f in special_files or f.endswith('.ent'): - if cfg.CONF.verbose: - print("File %s modified, this affects all books." % f) - return True - - return False - - -def get_modified_files(rootdir, filtering=None): - """Get modified files below doc directory.""" - - # There are several tree traversals in this program that do a - # chdir, we need to run this git command always from the rootdir, - # so assure that. - os.chdir(rootdir) - - try: - git_args = ["git", "diff", "--name-only", "--relative", "HEAD~1", - "HEAD"] - if filtering is not None: - git_args.append(filtering) - modified_files = subprocess.check_output( - git_args, - universal_newlines=True).strip().split() - except (subprocess.CalledProcessError, OSError) as e: - print("git failed: %s" % e) - sys.exit(1) - return modified_files - - -def filter_dirs(dirs): - """Return list of directories to descend into.""" - - # Don't descend into 'locale', 'target', and 'publish-docs' - # subdirectories and filter out any dot directories - - return [d for d in dirs if (d != 'target' and - d != 'publish-docs' and - d != 'locale' and - not d.startswith('.'))] - - -def check_deleted_files(rootdir, file_exceptions, verbose): - """Checking that no removed files are referenced.""" - - print("Checking that no removed files are referenced...") - deleted_files = get_modified_files(rootdir, "--diff-filter=D") - if not deleted_files: - print("No files were removed.\n") - return 0 - - if verbose: - print(" Removed files:") - for f in deleted_files: - print(" %s" % f) - - deleted_files = [os.path.abspath(x) for x in deleted_files] - no_checked_files = 0 - - # Figure out whether files were included anywhere - missing_reference = False - - for root, dirs, files in os.walk(rootdir): - dirs[:] = filter_dirs(dirs) - - os.chdir(root) - - for f in files: - if not is_testable_xml_file(f, file_exceptions): - continue - - path = os.path.abspath(os.path.join(root, f)) - try: - doc = etree.parse(path) - except etree.XMLSyntaxError as e: - print(" Warning: file %s is invalid XML: %s" % (path, e)) - continue - - no_checked_files = no_checked_files + 1 - - # Check for inclusion of files as part of imagedata - for node in doc.findall( - '//{http://docbook.org/ns/docbook}imagedata'): - href = node.get('fileref') - if (f not in file_exceptions and - os.path.abspath(href) in deleted_files): - print(" File %s has imagedata href for deleted " - "file %s" % (f, href)) - missing_reference = True - - break - - # Check for inclusion of files as part of xi:include - ns = {"xi": "http://www.w3.org/2001/XInclude"} - for node in doc.xpath('//xi:include', namespaces=ns): - href = node.get('href') - if (os.path.abspath(href) in deleted_files): - print(" File %s has an xi:include on deleted file %s" - % (f, href)) - missing_reference = True - - if missing_reference: - print("Check failed, %d files were removed, " - "%d files checked.\n" - % (len(deleted_files), no_checked_files)) - return 1 - - print("Check passed, %d files were removed, " - "%d files checked.\n" - % (len(deleted_files), no_checked_files)) - return 0 - - -def indent(text, spaces): - """Indent each line of a string by given number of spaces. - - The text argument is passed through str() first to turn objects such - as exceptions into strings. - """ - return ''.join((spaces * ' ') + i for i in str(text).splitlines(True)) - - -def validate_one_json_file(rootdir, path, verbose, check_syntax, - check_niceness): - """Validate a single JSON file.""" - - any_failures = False - if verbose: - print(" Validating %s" % os.path.relpath(path, rootdir)) - - try: - if check_syntax: - jsoncheck.check_syntax(path) - except ValueError as e: - any_failures = True - print(" Invalid JSON file %s:\n%s" % - (os.path.relpath(path, rootdir), indent(e, 4))) - else: - try: - if check_niceness: - jsoncheck.check_formatting(path) - except ValueError as e: - any_failures = True - print(" %s:\n%s" % (os.path.relpath(path, rootdir), - indent(e, 4))) - - try: - if check_niceness: - verify_whitespace_niceness(path) - verify_newline_end_of_file(path) - verify_unicode_niceness(path) - except ValueError as e: - any_failures = True - print(" %s: %s" % (os.path.relpath(path, rootdir), e)) - - return any_failures - - -def validate_one_file(schema, rootdir, path, verbose, - check_syntax, check_niceness, check_links, - validate_schema): - """Validate a single file.""" - # We pass schema in as a way of caching it, generating it is expensive - - any_failures = False - if verbose: - print(" Validating %s" % os.path.relpath(path, rootdir)) - try: - if check_syntax or check_links: - doc = etree.parse(path) - if check_syntax: - if validate_schema: - if validation_failed(schema, doc): - any_failures = True - print(error_message(schema.error_log)) - verify_section_tags_have_xmlid(doc) - verify_profiling(doc) - if check_links: - verify_valid_links(doc) - if check_niceness: - verify_whitespace_niceness(path) - verify_newline_end_of_file(path) - verify_unicode_niceness(path) - except etree.XMLSyntaxError as e: - any_failures = True - print(" %s: %s" % (os.path.relpath(path, rootdir), e)) - except ValueError as e: - any_failures = True - print(" %s: %s" % (os.path.relpath(path, rootdir), e)) - - return any_failures - - -def is_testable_xml_file(path, exceptions): - """Returns true if file ends with .xml and is not a pom.xml file.""" - - filename = os.path.basename(path) - return (filename.endswith('.xml') and not filename == 'pom.xml' and - filename not in exceptions) - - -def is_testable_file(path, exceptions): - """Returns true if file is in some XML format we handle - - Skips pom.xml files as well since those are not handled. - """ - - filename = os.path.basename(path) - return (filename.endswith(('.xml', '.xsd', '.xsl', '.wadl', - '.xjb', '.json')) and - not filename == 'pom.xml' and filename not in exceptions) - - -def is_wadl(filename): - """Returns true if file ends with .wadl.""" - - return filename.endswith('.wadl') - - -def is_json(filename): - """Returns true if file ends with .json.""" - - return filename.endswith('.json') - - -def validate_individual_files(files_to_check, rootdir, verbose, - check_syntax=False, check_niceness=False, - check_links=False, is_api_site=False): - """Validate list of files.""" - - schema = get_schema(is_api_site) - if is_api_site: - wadl_schema = get_wadl_schema() - - any_failures = False - no_validated = 0 - no_failed = 0 - - checks = [] - if check_links: - checks.append("valid URL links") - if check_niceness: - checks.append("niceness") - if check_syntax: - checks.append("syntax") - print("Checking files for %s..." % (", ".join(checks))) - - for f in files_to_check: - validate_schema = True - if is_api_site: - # Files ending with ".xml" in subdirectories of - # wadls and samples files are not docbook files. - if (f.endswith('.xml') and - ("wadls" in f or "samples" in f)): - validate_schema = False - # Right now we can only validate docbook .xml - # and .wadl files with a schema - elif not f.endswith(('.wadl', '.xml')): - validate_schema = False - - if is_json(f): - any_failures = validate_one_json_file(rootdir, f, - verbose, - check_syntax, - check_niceness) - elif (is_api_site and is_wadl(f)): - any_failures = validate_one_file(wadl_schema, rootdir, f, - verbose, - check_syntax, - check_niceness, - check_links, - validate_schema) - else: - any_failures = validate_one_file(schema, rootdir, f, - verbose, - check_syntax, - check_niceness, - check_links, - validate_schema) - if any_failures: - no_failed = no_failed + 1 - no_validated = no_validated + 1 - - if no_failed > 0: - print("Check failed, validated %d files with %d failures.\n" - % (no_validated, no_failed)) - return 1 - else: - print("Check passed, validated %d files.\n" % no_validated) - return 0 - - -def validate_modified_files(rootdir, exceptions, verbose, - check_syntax=False, check_niceness=False, - check_links=False, is_api_site=False): - """Validate list of modified, testable files.""" - - # Do not select deleted files, just Added, Copied, Modified, Renamed, - # or Type changed - modified_files = get_modified_files(rootdir, "--diff-filter=ACMRT") - modified_files = [f for f in modified_files if - is_testable_file(f, exceptions)] - - return validate_individual_files(modified_files, rootdir, - verbose, - check_syntax, check_niceness, - check_links, is_api_site) - - -def validate_all_files(rootdir, exceptions, verbose, - check_syntax, check_niceness=False, - check_links=False, is_api_site=False): - """Validate all testable files (XML, WADL, JSON, etc.).""" - - files_to_check = [] - - for root, dirs, files in os.walk(rootdir): - dirs[:] = filter_dirs(dirs) - - for f in files: - # Ignore maven files, which are called pom.xml - if is_testable_file(f, exceptions): - path = os.path.abspath(os.path.join(root, f)) - files_to_check.append(path) - - return validate_individual_files(files_to_check, rootdir, - verbose, - check_syntax, check_niceness, - check_links, is_api_site) - - -def logging_build_book(result): - """Callback for book building.""" - RESULTS_OF_BUILDS.append(result) - - -def get_gitroot(): - """Return path to top-level of git repository.""" - - try: - git_args = ["git", "rev-parse", "--show-toplevel"] - gitroot = subprocess.check_output(git_args, - universal_newlines=True).rstrip() - except (subprocess.CalledProcessError, OSError) as e: - print("git failed: %s" % e) - sys.exit(1) - return gitroot - - -def print_gitinfo(): - """Print information about repository and change.""" - - try: - git_cmd = ["git", "rev-parse", "--abbrev-ref", "HEAD"] - gitbranch = subprocess.check_output(git_cmd, - universal_newlines=True).rstrip() - git_cmd = ["git", "show", "--format=%s", "-s"] - gitsubject = subprocess.check_output(git_cmd, - universal_newlines=True).rstrip() - git_cmd = ["git", "show", "--format=%an", "-s"] - gitauthor = subprocess.check_output(git_cmd, - universal_newlines=True).rstrip() - except (subprocess.CalledProcessError, OSError) as e: - print("git failed: %s" % e) - sys.exit(1) - print("Testing patch:") - print(" Title: %s" % gitsubject) - print(" Author: %s" % gitauthor) - print(" Branch: %s" % gitbranch) - - -def get_publish_path(): - """Return path to use of publishing books.""" - - return os.path.join(get_gitroot(), 'publish-docs') - - -def ignore_for_publishing(_, names): - """Return list of files that should be ignored for publishing.""" - - # Ignore: - # - all files ending with .xml with the exception of atom.xml - # - all files ending with .fo - # The directory named wadls - - f = [n for n in names if ((n.endswith('.xml') and n != 'atom.xml') - or (n.endswith('.fo') or n == 'wadls'))] - return f - - -def publish_book(publish_path, book): - """Copy generated files to publish_path.""" - - # Assumption: The path for the book is the same as the name of directory - # the book is in. We need to special case any exceptions. - - # Publishing directory - book_path = publish_path - - if cfg.CONF.language: - book_path = os.path.join(book_path, cfg.CONF.language) - - if os.path.isdir(os.path.join('target/docbkx/webhelp', book)): - source = os.path.join('target/docbkx/webhelp', book) - elif os.path.isdir(os.path.join('target/docbkx/webhelp/local', book)): - source = os.path.join('target/docbkx/webhelp/local', book) - book_path = os.path.join(book_path, 'local') - elif os.path.isdir(os.path.join('target/docbkx/webhelp/', - cfg.CONF.release_path, book)): - source = os.path.join('target/docbkx/webhelp/', - cfg.CONF.release_path, book) - book_path = os.path.join(book_path, cfg.CONF.release_path) - elif (book in BOOK_MAPPINGS): - source = BOOK_MAPPINGS[book] - else: - if cfg.CONF.debug: - print("No build result found for book %s" % book) - return - - if book in BOOK_PUBLISH_MAPPINGS: - book_publish_dir = BOOK_PUBLISH_MAPPINGS[book] - else: - book_publish_dir = book - - book_path = os.path.join(book_path, book_publish_dir) - if cfg.CONF.debug: - print("Uploading book %s to %s" % (book, book_path)) - - # Note that shutil.copytree does not allow an existing target directory, - # thus delete it. - shutil.rmtree(book_path, ignore_errors=True) - - shutil.copytree(source, book_path, - ignore=ignore_for_publishing) - - -def ensure_exists(program): - """Check that program exists, abort if not.""" - retcode = subprocess.call(['which', program], stdout=subprocess.PIPE, - stderr=subprocess.PIPE) - if retcode != 0: - print("Program '%s' does not exist, please install!" % program) - sys.exit(1) - - -def build_book(book, publish_path, log_path): - """Build book(s) in directory book.""" - - # Note that we cannot build in parallel several books in the same - # directory like the Install Guide. Thus we build sequentially per - # directory. - os.chdir(book) - result = True - returncode = 0 - if cfg.CONF.debug: - print("Building in directory '%s'" % book) - base_book = os.path.basename(book) - base_book_orig = base_book - comments = "-Dcomments.enabled=%s" % cfg.CONF.comments_enabled - release = "-Drelease.path.name=%s" % cfg.CONF.release_path - if cfg.CONF.language: - out_filename = ("build-" + cfg.CONF.language + "-" + base_book + - ".log.gz") - else: - out_filename = "build-" + base_book + ".log.gz" - out_file = gzip.open(os.path.join(log_path, out_filename), 'w') - output = "" - try: - # Clean first and then build so that the output of all guides - # is available - output = subprocess.check_output( - ["mvn", "clean"], - stderr=subprocess.STDOUT - ) - out_file.write(output) - if base_book == "install-guide": - # Build Debian - if cfg.CONF.enable_debian_install: - base_book = "install-guide (for debian)" - output = subprocess.check_output( - ["mvn", "generate-sources", "-B", - comments, release, - "-Doperating.system=apt-debian", "-Dprofile.os=debian"], - stderr=subprocess.STDOUT - ) - out_file.write(output) - # Build Fedora - base_book = "install-guide (for Fedora)" - output = subprocess.check_output( - ["mvn", "generate-sources", "-B", - comments, release, - "-Doperating.system=yum", - "-Dprofile.os=centos;fedora;rhel"], - stderr=subprocess.STDOUT - ) - out_file.write(output) - # Build openSUSE - base_book = "install-guide (for openSUSE)" - output = subprocess.check_output( - ["mvn", "generate-sources", "-B", - comments, release, - "-Doperating.system=zypper", "-Dprofile.os=opensuse;sles"], - stderr=subprocess.STDOUT - ) - out_file.write(output) - # Build Ubuntu - base_book = "install-guide (for Ubuntu)" - output = subprocess.check_output( - ["mvn", "generate-sources", "-B", - comments, release, - "-Doperating.system=apt", "-Dprofile.os=ubuntu"], - stderr=subprocess.STDOUT - ) - # Success - base_book = "install-guide (for " - if cfg.CONF.enable_debian_install: - base_book += "Debian, " - base_book += "Fedora, openSUSE, Ubuntu)" - # HOT template guide - elif base_book == 'hot-guide': - # Make sure that the build dir is clean - if os.path.isdir('build'): - shutil.rmtree('build') - # Generate the DN XML - output = subprocess.check_output( - ["make", "xml"], - stderr=subprocess.STDOUT - ) - out_file.write(output) - # Generate the docbook book - output = subprocess.check_output( - ["openstack-dn2osdbk", "build/xml", "build/docbook", - "--toplevel", "book"], - stderr=subprocess.STDOUT - ) - out_file.write(output) - output = subprocess.check_output( - ["mvn", "generate-sources", comments, release, "-B"], - stderr=subprocess.STDOUT - ) - else: - output = subprocess.check_output( - ["mvn", "generate-sources", comments, release, "-B"], - stderr=subprocess.STDOUT - ) - except (subprocess.CalledProcessError, KeyboardInterrupt) as e: - output = e.output - returncode = e.returncode - result = False - - out_file.write(output) - out_file.close() - if result: - publish_book(publish_path, base_book_orig) - return (base_book, result, output, returncode) - - -def is_book_master(filename): - """Check if a file is a book master file. - - Returns True if filename is one of the special filenames used for the - book master files. - - We do not parse pom.xml for the includes directive to determine - the top-level files and thus have to use a heuristic. - - """ - - return ((filename.startswith(('bk-', 'bk_', 'st-', 'api-')) - and filename.endswith('.xml')) or - filename == 'openstack-glossary.xml') - - -def print_unused(rootdir, ignore_dirs, included_by): - """Print list of files that are not included anywhere.""" - - if cfg.CONF.print_unused_files: - print("Checking for files that are not included anywhere...") - print(" Note: This only looks at files included by an .xml file " - "but not for files included by other files like .wadl.") - for root, dirs, files in os.walk(rootdir): - dirs[:] = filter_dirs(dirs) - - # Filter out directories to be ignored - if ignore_dirs: - dirs[:] = [d for d in dirs if d not in ignore_dirs] - - for f in files: - if not f.endswith('.xml'): - continue - f_base = os.path.basename(f) - f_abs = os.path.abspath(os.path.join(root, f)) - - if (f_abs not in included_by and f_base != "pom.xml" - and not is_book_master(f_base)): - f_rel = os.path.relpath(f_abs, rootdir) - print(" %s " % f_rel) - print("\n") - - -def generate_affected_books(rootdir, book_bk, ignore_dirs, abs_ignore_dirs, - included_by): - """Generate list of affected books.""" - - affected_books = set() - - # Generate list of modified_files - # Do not select deleted files, just Added, Copied, Modified, Renamed, - # or Type changed - modified_files = get_modified_files(rootdir, "--diff-filter=ACMRT") - modified_files = [os.path.abspath(f) for f in modified_files] - if ignore_dirs: - for idir in abs_ignore_dirs: - non_ignored_files = [] - for f in modified_files: - if not f.startswith(idir): - non_ignored_files.append(f) - modified_files = non_ignored_files - - # 2. Find all modified files and where they are included - - # List of files that we have to iterate over, these are affected - # by some modification - new_files = modified_files - - # All files that are affected (either directly or indirectly) - affected_files = set(modified_files) - - # 3. Iterate over files that have includes on modified files - # and build a closure - the set of all files (affected_files) - # that have a path to a modified file via includes. - while new_files: - new_files_to_check = new_files - new_files = [] - for f in new_files_to_check: - if "doc/hot-guide/" in f: - affected_books.add('hot-guide') - continue - # Skip bk*.xml files - if is_book_master(os.path.basename(f)): - book_modified = book_bk[f] - if book_modified not in affected_books: - affected_books.add(book_modified) - continue - if f not in included_by: - continue - for g in included_by[f]: - if g not in affected_files: - new_files.append(g) - affected_files.add(g) - return affected_books - - -def find_affected_books(rootdir, book_exceptions, file_exceptions, - force, ignore_dirs): - """Check which books are affected by modified files. - - Returns a set with books. - """ - book_root = rootdir - - books = [] - - build_all_books = (force or check_modified_affects_all(rootdir) or - cfg.CONF.only_book) - - # Dictionary that contains a set of files. - # The key is a filename, the set contains files that include this file. - included_by = {} - - # Dictionary with books and their bk*.xml files - book_bk = {} - - # List of absolute paths of ignored directories - abs_ignore_dirs = [] - # 1. Iterate over whole tree and analyze include files. - # This updates included_by, book_bk and books. - for root, dirs, files in os.walk(rootdir): - dirs[:] = filter_dirs(dirs) - - # Filter out directories to be ignored - if ignore_dirs: - for d in dirs: - if d in ignore_dirs: - abs_ignore_dirs.append( - os.path.join(os.path.join(root, d))) - dirs[:] = [d for d in dirs if d not in ignore_dirs] - - if os.path.basename(root) in book_exceptions: - break - # Do not process files in doc itself or top-level directory - elif root.endswith('doc') or root == rootdir: - continue - elif ("pom.xml" in files and (not cfg.CONF.only_book or - os.path.basename(root) in - cfg.CONF.only_book)): - books.append(root) - book_root = root - - # No need to check single books if we build all, we just - # collect list of books - if build_all_books: - continue - - for f in files: - f_base = os.path.basename(f) - f_abs = os.path.abspath(os.path.join(root, f)) - if is_book_master(f_base): - book_bk[f_abs] = book_root - if not is_testable_xml_file(f, file_exceptions): - continue - - try: - doc = etree.parse(f_abs) - except etree.XMLSyntaxError as e: - print(" Warning: file %s is invalid XML: %s" % (f_abs, e)) - continue - for node in doc.findall( - '//{http://docbook.org/ns/docbook}imagedata'): - href = node.get('fileref') - href_abs = os.path.abspath(os.path.join(root, href)) - if href_abs in included_by: - included_by[href_abs].add(f_abs) - else: - included_by[href_abs] = set([f_abs]) - - ns = {"xi": "http://www.w3.org/2001/XInclude"} - for node in doc.xpath('//xi:include', namespaces=ns): - href = node.get('href') - href_abs = os.path.abspath(os.path.join(root, href)) - if href_abs in included_by: - included_by[href_abs].add(f_abs) - else: - included_by[href_abs] = set([f_abs]) - - ns = {"wadl": "http://wadl.dev.java.net/2009/02"} - for node in doc.xpath('//wadl:resource', namespaces=ns): - href = node.get('href') - hash_sign = href.rfind('#') - if hash_sign != -1: - href = href[:hash_sign] - href_abs = os.path.abspath(os.path.join(root, href)) - if href_abs in included_by: - included_by[href_abs].add(f_abs) - else: - included_by[href_abs] = set([f_abs]) - for node in doc.xpath('//wadl:resources', namespaces=ns): - href = node.get('href') - # wadl:resources either have a href directly or a child - # wadl:resource that has a href. So, check that we have - # a href. - if href: - hash_sign = href.rfind('#') - if hash_sign != -1: - href = href[:hash_sign] - href_abs = os.path.abspath(os.path.join(root, href)) - if href_abs in included_by: - included_by[href_abs].add(f_abs) - else: - included_by[href_abs] = set([f_abs]) - - print_unused(rootdir, ignore_dirs, included_by) - - if cfg.CONF.only_book: - print("Building specified books.") - elif build_all_books: - print("Building all books.") - else: - affected_books = generate_affected_books(rootdir, book_bk, ignore_dirs, - abs_ignore_dirs, included_by) - if affected_books: - books = affected_books - else: - print("No books are affected by modified files. " - "Building all books.") - - return books - - -def build_affected_books(rootdir, book_exceptions, file_exceptions, - force=False, ignore_dirs=None, - ignore_books=None): - """Build all the books which are affected by modified files. - - Looks for all directories with "pom.xml" and checks if a - XML file in the directory includes a modified file. If at least - one XML file includes a modified file the method calls - "mvn clean generate-sources" in that directory. - - This will throw an exception if a book fails to build - """ - - if ignore_dirs is None: - ignore_dirs = [] - - books = find_affected_books(rootdir, book_exceptions, - file_exceptions, force, ignore_dirs) - - if ignore_books: - books = [b for b in books if os.path.basename(b) not in ignore_books] - - # Remove cache content which can cause build failures - shutil.rmtree(os.path.expanduser("~/.fop"), - ignore_errors=True) - - maxjobs = multiprocessing.cpu_count() - # Jenkins fails sometimes with errors if too many jobs run, artificially - # limit to 4 for now. - # See https://bugs.launchpad.net/openstack-manuals/+bug/1221721 - if maxjobs > 4: - maxjobs = 4 - pool = multiprocessing.Pool(maxjobs) - print("Queuing the following books for building:") - publish_path = get_publish_path() - log_path = get_gitroot() - first_book = True - - # First show books - for book in sorted(books): - print(" %s" % os.path.basename(book)) - print("Building all queued %d books now..." % len(books)) - - # And then queue - since we wait for the first book to finish. - try: - for book in sorted(books): - if cfg.CONF.debug or not cfg.CONF.parallel: - (book, result, output, retcode) = build_book(book, - publish_path, - log_path) - logging_build_book([book, result, output, retcode]) - else: - res = pool.apply_async(build_book, - (book, publish_path, log_path), - callback=logging_build_book) - if first_book: - first_book = False - # The first invocation of maven might download loads of - # data locally, we cannot do this in parallel. So, wait - # here for the first job to finish before running further - # mvn jobs. - res.get() - pool.close() - pool.join() - except KeyboardInterrupt: - pool.terminate() - pool.join() - - any_failures = False - for book, result, _, _ in sorted(RESULTS_OF_BUILDS, - key=operator.itemgetter(0)): - if result: - print(">>> Build of book %s succeeded." % book) - else: - any_failures = True - - if cfg.CONF.create_index: - index.generate_index_file(get_publish_path()) - - if any_failures: - for book, result, output, returncode in RESULTS_OF_BUILDS: - if not result: - print(">>> Build of book %s failed (returncode = %d)." - % (book, returncode)) - print("\n%s" % output) - - print("Building of books finished with failures.\n") - return 1 - else: - print("Building of books finished successfully.\n") - - if len(RESULTS_OF_BUILDS) != len(books): - print("ERROR: %d queued for building but only %d build!" % - (len(books), len(RESULTS_OF_BUILDS))) - return 1 - return 0 - - -def add_exceptions(file_exception, verbose): - """Add list of exceptions from file_exceptions.""" - - for entry in file_exception: - if verbose: - print(" Adding file to ignore list: %s" % entry) - FILE_EXCEPTIONS.append(entry) - - -def add_build_exceptions(build_file_exception, verbose): - """Add list of exceptions from build_file_exceptions.""" - - for entry in build_file_exception: - if verbose: - print(" Adding file to build ignore list: %s" % entry) - BUILD_FILE_EXCEPTIONS.append(entry) - - -def add_url_exceptions(url_exception, verbose): - """Add list of exceptions from url_exception.""" - - for entry in url_exception: - if verbose: - print(" Adding URL to ignore list: %s" % entry) - URL_EXCEPTIONS.append(entry) - - -cli_OPTS = [ - cfg.BoolOpt("api-site", default=False, - help="Enable special handling for api-site repository."), - cfg.BoolOpt('check-all', default=False, - help="Run all checks."), - cfg.BoolOpt('check-build', default=False, - help="Check building of books using modified files."), - cfg.BoolOpt("check-deletions", default=False, - help="Check that deleted files are not used."), - cfg.BoolOpt("check-links", default=False, - help="Check that linked URLs are valid and reachable."), - cfg.BoolOpt("check-niceness", default=False, - help="Check the niceness of files, for example whitespace."), - cfg.BoolOpt("check-syntax", default=False, - help="Check the syntax of modified files."), - cfg.BoolOpt("create-index", default=True, - help="When publishing create an index.html file to find books " - "in an easy way."), - cfg.BoolOpt('force', default=False, - help="Force the validation of all files " - "and build all books."), - cfg.BoolOpt("parallel", default=True, - help="Build books in parallel (default)."), - cfg.BoolOpt("print-unused-files", default=False, - help="Print list of files that are not included anywhere as " - "part of check-build."), - cfg.BoolOpt("publish", default=False, - help="Setup content in publish-docs directory for " - "publishing to external website."), - cfg.MultiStrOpt("build-file-exception", - help="File that will be skipped during delete and " - "build checks to generate dependencies. This should " - "be done for invalid XML files only."), - cfg.MultiStrOpt("file-exception", - help="File that will be skipped during niceness and " - "syntax validation."), - cfg.MultiStrOpt("ignore-dir", - help="Directory to ignore for building of manuals. The " - "parameter can be passed multiple times to add " - "several directories."), - cfg.MultiStrOpt("ignore-book", - help="Book to ignore when building manuals. The " - "parameter can be passed multiple times to add " - "several books."), - cfg.StrOpt('language', default=None, short='l', - help="Build translated manual for language in path " - "generate/$LANGUAGE ."), - cfg.MultiStrOpt('only-book', default=None, - help="Build each specified manual."), - cfg.MultiStrOpt("url-exception", - help="URL that will be skipped during reachability " - "check."), - cfg.BoolOpt("enable-debian-install", default=False, - help="Enable building of Debian Install Guide."), -] - -OPTS = [ - # NOTE(jaegerandi): books, target-dirs, publish-dir could be a - # DictOpt but I could not get this working properly. - cfg.MultiStrOpt("book", default=None, - help="Name of book that needs special mapping. " - "This is the name of directory where the pom.xml " - "file lives."), - cfg.MultiStrOpt("target-dir", default=None, - help="Directory name in target dir for a book. " - "The option must be in the same order as the book " - "option."), - cfg.MultiStrOpt("publish-dir", default=None, - help="Directory name where book will be copied to " - "in publish-docs directory. This option must be in " - "same order as the book option. Either give this option " - "for all books or for none. If publish-dir is not " - "specified, book is used as publish-dir."), - cfg.StrOpt("repo-name", default=None, - help="Name of repository."), - cfg.StrOpt("release-path", default="trunk", - help="Value to pass to maven for release.path.name."), - cfg.StrOpt("comments-enabled", default="0", - help="Value to pass to maven for comments.enabled."), -] - - -def handle_options(): - """Setup configuration variables from config file and options.""" - - CONF = cfg.CONF - CONF.register_cli_opts(cli_OPTS) - CONF.register_opts(OPTS) - - default_config_files = [os.path.join(get_gitroot(), 'doc-test.conf')] - CONF(sys.argv[1:], project='documentation', prog='openstack-doc-test', - version=os_doc_tools.__version__, - default_config_files=default_config_files) - - if CONF.repo_name: - print("Testing repository '%s'\n" % CONF.repo_name) - - if CONF.verbose: - print("Verbose execution") - - if CONF.debug: - print("Enabling debug code") - - if CONF.language: - print("Building for language '%s'" % CONF.language) - - if CONF.file_exception: - add_exceptions(CONF.file_exception, CONF.verbose) - - if CONF.build_file_exception: - add_build_exceptions(CONF.build_file_exception, CONF.verbose) - - if CONF.url_exception: - add_url_exceptions(CONF.url_exception, CONF.verbose) - - if (not CONF.check_build and not CONF.check_deletions and - not CONF.check_niceness and not CONF.check_syntax and - not CONF.check_links): - CONF.check_all = True - - if CONF.check_all: - CONF.check_deletions = True - CONF.check_build = True - CONF.check_links = True - CONF.check_niceness = True - CONF.check_syntax = True - - if CONF.publish: - CONF.create_index = False - - if CONF.check_build and CONF.book and CONF.target_dir: - if len(CONF.book) != len(CONF.target_dir): - print("ERROR: book and target_dir options need to have a 1:1 " - "relationship.") - sys.exit(1) - if (CONF.publish_dir and - len(CONF.publish_dir) != len(CONF.target_dir)): - print("ERROR: publish_dir and target_dir need to have a 1:1 " - "relationship if publish_dir is specified.") - sys.exit(1) - for i in range(len(CONF.book)): - BOOK_MAPPINGS[CONF.book[i]] = CONF.target_dir[i] - if CONF.verbose: - print(" Target dir for %s is %s" % - (CONF.book[i], BOOK_MAPPINGS[CONF.book[i]])) - if CONF.publish_dir: - for i in range(len(CONF.book)): - BOOK_PUBLISH_MAPPINGS[CONF.book[i]] = CONF.publish_dir[i] - if CONF.verbose: - print(" Publish dir for %s is %s" % - (CONF.book[i], BOOK_PUBLISH_MAPPINGS[CONF.book[i]])) - - if CONF.check_build: - if CONF.verbose: - if cfg.CONF.ignore_dir: - for d in cfg.CONF.ignore_dir: - print(" Ignore directory: %s" % d) - print(" Release path: %s" % cfg.CONF.release_path) - print(" Comments enabled: %s" % cfg.CONF.comments_enabled) - - -def check_no_building(): - """Figure out whether we need to build XML files.""" - - CONF = cfg.CONF - if not CONF.force and www_touched(): - print("Only files in www directory changed, nothing to do.\n") - return True - # Build everything if we publish so that regularly all manuals are - # published, for testing ignore the locale directories. - if (not CONF.force and not CONF.publish and not CONF.language - and only_po_touched()): - print("Only files in locale directories changed, nothing to do.\n") - return True - # If only RST files are touched, there's nothing to do. - if (not CONF.force and only_rst_touched()): - print("Only RST files changed, nothing to do.\n") - return True - return False - - -def doctest(): - """Central entrypoint, parses arguments and runs tests.""" - - start_time = time.time() - CONF = cfg.CONF - print("\nOpenStack Doc Checks (using openstack-doc-tools version %s)\n" - % os_doc_tools.__version__) - try: - handle_options() - except cfg.Error as e: - print(e) - return 1 - print_gitinfo() - errors = 0 - - doc_path = get_gitroot() - if CONF.language: - doc_path = os.path.join(doc_path, 'generated', CONF.language) - if CONF.verbose: - print("Using %s as root" % doc_path) - elif not CONF.api_site: - doc_path = os.path.join(doc_path, 'doc') - - if check_no_building(): - if CONF.create_index: - index.generate_index_file(get_publish_path()) - return - - if CONF.check_syntax or CONF.check_niceness or CONF.check_links: - if CONF.force: - errors += validate_all_files(doc_path, FILE_EXCEPTIONS, - CONF.verbose, - CONF.check_syntax, - CONF.check_niceness, - CONF.check_links, - CONF.api_site) - else: - errors += validate_modified_files(doc_path, FILE_EXCEPTIONS, - CONF.verbose, - CONF.check_syntax, - CONF.check_niceness, - CONF.check_links, - CONF.api_site) - - if CONF.check_deletions: - errors += check_deleted_files(doc_path, BUILD_FILE_EXCEPTIONS, - CONF.verbose) - - if CONF.check_build: - # Some programs are called in subprocesses, make sure that they - # really exist. - ensure_exists("mvn") - errors += build_affected_books(doc_path, BOOK_EXCEPTIONS, - BUILD_FILE_EXCEPTIONS, - CONF.force, - CONF.ignore_dir, - CONF.ignore_book) - - elapsed_time = (time.time() - start_time) - print("Run time was: %.2f seconds." % elapsed_time) - if errors == 0: - print("Congratulations, all tests passed!") - return 0 - else: - print("Some tests failed!") - return 1 - -if __name__ == "__main__": - sys.exit(doctest()) diff --git a/os_doc_tools/openstack/__init__.py b/os_doc_tools/openstack/__init__.py deleted file mode 100644 index e69de29b..00000000 diff --git a/os_doc_tools/openstack/common/__init__.py b/os_doc_tools/openstack/common/__init__.py deleted file mode 100644 index d1223eaf..00000000 --- a/os_doc_tools/openstack/common/__init__.py +++ /dev/null @@ -1,17 +0,0 @@ -# -# Licensed under the Apache License, Version 2.0 (the "License"); you may -# not use this file except in compliance with the License. You may obtain -# a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT -# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the -# License for the specific language governing permissions and limitations -# under the License. - -import six - - -six.add_move(six.MovedModule('mox', 'mox', 'mox3.mox')) diff --git a/os_doc_tools/openstack/common/gettextutils.py b/os_doc_tools/openstack/common/gettextutils.py deleted file mode 100644 index e7a31f65..00000000 --- a/os_doc_tools/openstack/common/gettextutils.py +++ /dev/null @@ -1,479 +0,0 @@ -# Copyright 2012 Red Hat, Inc. -# Copyright 2013 IBM Corp. -# All Rights Reserved. -# -# Licensed under the Apache License, Version 2.0 (the "License"); you may -# not use this file except in compliance with the License. You may obtain -# a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT -# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the -# License for the specific language governing permissions and limitations -# under the License. - -""" -gettext for openstack-common modules. - -Usual usage in an openstack.common module: - - from os_doc_tools.openstack.common.gettextutils import _ -""" - -import copy -import gettext -import locale -from logging import handlers -import os - -from babel import localedata -import six - -_AVAILABLE_LANGUAGES = {} - -# FIXME(dhellmann): Remove this when moving to oslo.i18n. -USE_LAZY = False - - -class TranslatorFactory(object): - """Create translator functions - """ - - def __init__(self, domain, localedir=None): - """Establish a set of translation functions for the domain. - - :param domain: Name of translation domain, - specifying a message catalog. - :type domain: str - :param lazy: Delays translation until a message is emitted. - Defaults to False. - :type lazy: Boolean - :param localedir: Directory with translation catalogs. - :type localedir: str - """ - self.domain = domain - if localedir is None: - localedir = os.environ.get(domain.upper() + '_LOCALEDIR') - self.localedir = localedir - - def _make_translation_func(self, domain=None): - """Return a new translation function ready for use. - - Takes into account whether or not lazy translation is being - done. - - The domain can be specified to override the default from the - factory, but the localedir from the factory is always used - because we assume the log-level translation catalogs are - installed in the same directory as the main application - catalog. - - """ - if domain is None: - domain = self.domain - t = gettext.translation(domain, - localedir=self.localedir, - fallback=True) - # Use the appropriate method of the translation object based - # on the python version. - m = t.gettext if six.PY3 else t.ugettext - - def f(msg): - """oslo.i18n.gettextutils translation function.""" - if USE_LAZY: - return Message(msg, domain=domain) - return m(msg) - return f - - @property - def primary(self): - "The default translation function." - return self._make_translation_func() - - def _make_log_translation_func(self, level): - return self._make_translation_func(self.domain + '-log-' + level) - - @property - def log_info(self): - "Translate info-level log messages." - return self._make_log_translation_func('info') - - @property - def log_warning(self): - "Translate warning-level log messages." - return self._make_log_translation_func('warning') - - @property - def log_error(self): - "Translate error-level log messages." - return self._make_log_translation_func('error') - - @property - def log_critical(self): - "Translate critical-level log messages." - return self._make_log_translation_func('critical') - - -# NOTE(dhellmann): When this module moves out of the incubator into -# oslo.i18n, these global variables can be moved to an integration -# module within each application. - -# Create the global translation functions. -_translators = TranslatorFactory('os_doc_tools') - -# The primary translation function using the well-known name "_" -_ = _translators.primary - -# Translators for log levels. -# -# The abbreviated names are meant to reflect the usual use of a short -# name like '_'. The "L" is for "log" and the other letter comes from -# the level. -_LI = _translators.log_info -_LW = _translators.log_warning -_LE = _translators.log_error -_LC = _translators.log_critical - -# NOTE(dhellmann): End of globals that will move to the application's -# integration module. - - -def enable_lazy(): - """Convenience function for configuring _() to use lazy gettext - - Call this at the start of execution to enable the gettextutils._ - function to use lazy gettext functionality. This is useful if - your project is importing _ directly instead of using the - gettextutils.install() way of importing the _ function. - """ - global USE_LAZY - USE_LAZY = True - - -def install(domain): - """Install a _() function using the given translation domain. - - Given a translation domain, install a _() function using gettext's - install() function. - - The main difference from gettext.install() is that we allow - overriding the default localedir (e.g. /usr/share/locale) using - a translation-domain-specific environment variable (e.g. - NOVA_LOCALEDIR). - - Note that to enable lazy translation, enable_lazy must be - called. - - :param domain: the translation domain - """ - from six import moves - tf = TranslatorFactory(domain) - moves.builtins.__dict__['_'] = tf.primary - - -class Message(six.text_type): - """A Message object is a unicode object that can be translated. - - Translation of Message is done explicitly using the translate() method. - For all non-translation intents and purposes, a Message is simply unicode, - and can be treated as such. - """ - - def __new__(cls, msgid, msgtext=None, params=None, - domain='os_doc_tools', *args): - """Create a new Message object. - - In order for translation to work gettext requires a message ID, this - msgid will be used as the base unicode text. It is also possible - for the msgid and the base unicode text to be different by passing - the msgtext parameter. - """ - # If the base msgtext is not given, we use the default translation - # of the msgid (which is in English) just in case the system locale is - # not English, so that the base text will be in that locale by default. - if not msgtext: - msgtext = Message._translate_msgid(msgid, domain) - # We want to initialize the parent unicode with the actual object that - # would have been plain unicode if 'Message' was not enabled. - msg = super(Message, cls).__new__(cls, msgtext) - msg.msgid = msgid - msg.domain = domain - msg.params = params - return msg - - def translate(self, desired_locale=None): - """Translate this message to the desired locale. - - :param desired_locale: The desired locale to translate the message to, - if no locale is provided the message will be - translated to the system's default locale. - - :returns: the translated message in unicode - """ - - translated_message = Message._translate_msgid(self.msgid, - self.domain, - desired_locale) - if self.params is None: - # No need for more translation - return translated_message - - # This Message object may have been formatted with one or more - # Message objects as substitution arguments, given either as a single - # argument, part of a tuple, or as one or more values in a dictionary. - # When translating this Message we need to translate those Messages too - translated_params = _translate_args(self.params, desired_locale) - - translated_message = translated_message % translated_params - - return translated_message - - @staticmethod - def _translate_msgid(msgid, domain, desired_locale=None): - if not desired_locale: - system_locale = locale.getdefaultlocale() - # If the system locale is not available to the runtime use English - if not system_locale[0]: - desired_locale = 'en_US' - else: - desired_locale = system_locale[0] - - locale_dir = os.environ.get(domain.upper() + '_LOCALEDIR') - lang = gettext.translation(domain, - localedir=locale_dir, - languages=[desired_locale], - fallback=True) - if six.PY3: - translator = lang.gettext - else: - translator = lang.ugettext - - translated_message = translator(msgid) - return translated_message - - def __mod__(self, other): - # When we mod a Message we want the actual operation to be performed - # by the parent class (i.e. unicode()), the only thing we do here is - # save the original msgid and the parameters in case of a translation - params = self._sanitize_mod_params(other) - unicode_mod = super(Message, self).__mod__(params) - modded = Message(self.msgid, - msgtext=unicode_mod, - params=params, - domain=self.domain) - return modded - - def _sanitize_mod_params(self, other): - """Sanitize the object being modded with this Message. - - - Add support for modding 'None' so translation supports it - - Trim the modded object, which can be a large dictionary, to only - those keys that would actually be used in a translation - - Snapshot the object being modded, in case the message is - translated, it will be used as it was when the Message was created - """ - if other is None: - params = (other,) - elif isinstance(other, dict): - # Merge the dictionaries - # Copy each item in case one does not support deep copy. - params = {} - if isinstance(self.params, dict): - for key, val in self.params.items(): - params[key] = self._copy_param(val) - for key, val in other.items(): - params[key] = self._copy_param(val) - else: - params = self._copy_param(other) - return params - - def _copy_param(self, param): - try: - return copy.deepcopy(param) - except Exception: - # Fallback to casting to unicode this will handle the - # python code-like objects that can't be deep-copied - return six.text_type(param) - - def __add__(self, other): - msg = _('Message objects do not support addition.') - raise TypeError(msg) - - def __radd__(self, other): - return self.__add__(other) - - if six.PY2: - def __str__(self): - # NOTE(luisg): Logging in python 2.6 tries to str() log records, - # and it expects specifically a UnicodeError in order to proceed. - msg = _('Message objects do not support str() because they may ' - 'contain non-ascii characters. ' - 'Please use unicode() or translate() instead.') - raise UnicodeError(msg) - - -def get_available_languages(domain): - """Lists the available languages for the given translation domain. - - :param domain: the domain to get languages for - """ - if domain in _AVAILABLE_LANGUAGES: - return copy.copy(_AVAILABLE_LANGUAGES[domain]) - - localedir = '%s_LOCALEDIR' % domain.upper() - find = lambda x: gettext.find(domain, - localedir=os.environ.get(localedir), - languages=[x]) - - # NOTE(mrodden): en_US should always be available (and first in case - # order matters) since our in-line message strings are en_US - language_list = ['en_US'] - # NOTE(luisg): Babel <1.0 used a function called list(), which was - # renamed to locale_identifiers() in >=1.0, the requirements master list - # requires >=0.9.6, uncapped, so defensively work with both. We can remove - # this check when the master list updates to >=1.0, and update all projects - list_identifiers = (getattr(localedata, 'list', None) or - getattr(localedata, 'locale_identifiers')) - locale_identifiers = list_identifiers() - - for i in locale_identifiers: - if find(i) is not None: - language_list.append(i) - - # NOTE(luisg): Babel>=1.0,<1.3 has a bug where some OpenStack supported - # locales (e.g. 'zh_CN', and 'zh_TW') aren't supported even though they - # are perfectly legitimate locales: - # https://github.com/mitsuhiko/babel/issues/37 - # In Babel 1.3 they fixed the bug and they support these locales, but - # they are still not explicitly "listed" by locale_identifiers(). - # That is why we add the locales here explicitly if necessary so that - # they are listed as supported. - aliases = {'zh': 'zh_CN', - 'zh_Hant_HK': 'zh_HK', - 'zh_Hant': 'zh_TW', - 'fil': 'tl_PH'} - for (locale_, alias) in six.iteritems(aliases): - if locale_ in language_list and alias not in language_list: - language_list.append(alias) - - _AVAILABLE_LANGUAGES[domain] = language_list - return copy.copy(language_list) - - -def translate(obj, desired_locale=None): - """Gets the translated unicode representation of the given object. - - If the object is not translatable it is returned as-is. - If the locale is None the object is translated to the system locale. - - :param obj: the object to translate - :param desired_locale: the locale to translate the message to, if None the - default system locale will be used - :returns: the translated object in unicode, or the original object if - it could not be translated - """ - message = obj - if not isinstance(message, Message): - # If the object to translate is not already translatable, - # let's first get its unicode representation - message = six.text_type(obj) - if isinstance(message, Message): - # Even after unicoding() we still need to check if we are - # running with translatable unicode before translating - return message.translate(desired_locale) - return obj - - -def _translate_args(args, desired_locale=None): - """Translates all the translatable elements of the given arguments object. - - This method is used for translating the translatable values in method - arguments which include values of tuples or dictionaries. - If the object is not a tuple or a dictionary the object itself is - translated if it is translatable. - - If the locale is None the object is translated to the system locale. - - :param args: the args to translate - :param desired_locale: the locale to translate the args to, if None the - default system locale will be used - :returns: a new args object with the translated contents of the original - """ - if isinstance(args, tuple): - return tuple(translate(v, desired_locale) for v in args) - if isinstance(args, dict): - translated_dict = {} - for (k, v) in six.iteritems(args): - translated_v = translate(v, desired_locale) - translated_dict[k] = translated_v - return translated_dict - return translate(args, desired_locale) - - -class TranslationHandler(handlers.MemoryHandler): - """Handler that translates records before logging them. - - The TranslationHandler takes a locale and a target logging.Handler object - to forward LogRecord objects to after translating them. This handler - depends on Message objects being logged, instead of regular strings. - - The handler can be configured declaratively in the logging.conf as follows: - - [handlers] - keys = translatedlog, translator - - [handler_translatedlog] - class = handlers.WatchedFileHandler - args = ('/var/log/api-localized.log',) - formatter = context - - [handler_translator] - class = openstack.common.log.TranslationHandler - target = translatedlog - args = ('zh_CN',) - - If the specified locale is not available in the system, the handler will - log in the default locale. - """ - - def __init__(self, locale=None, target=None): - """Initialize a TranslationHandler - - :param locale: locale to use for translating messages - :param target: logging.Handler object to forward - LogRecord objects to after translation - """ - # NOTE(luisg): In order to allow this handler to be a wrapper for - # other handlers, such as a FileHandler, and still be able to - # configure it using logging.conf, this handler has to extend - # MemoryHandler because only the MemoryHandlers' logging.conf - # parsing is implemented such that it accepts a target handler. - handlers.MemoryHandler.__init__(self, capacity=0, target=target) - self.locale = locale - - def setFormatter(self, fmt): - self.target.setFormatter(fmt) - - def emit(self, record): - # We save the message from the original record to restore it - # after translation, so other handlers are not affected by this - original_msg = record.msg - original_args = record.args - - try: - self._translate_and_log_record(record) - finally: - record.msg = original_msg - record.args = original_args - - def _translate_and_log_record(self, record): - record.msg = translate(record.msg, self.locale) - - # In addition to translating the message, we also need to translate - # arguments that were passed to the log method that were not part - # of the main message e.g., log.info(_('Some message %s'), this_one)) - record.args = _translate_args(record.args, self.locale) - - self.target.emit(record) diff --git a/os_doc_tools/openstack/common/importutils.py b/os_doc_tools/openstack/common/importutils.py deleted file mode 100644 index 3099d272..00000000 --- a/os_doc_tools/openstack/common/importutils.py +++ /dev/null @@ -1,73 +0,0 @@ -# Copyright 2011 OpenStack Foundation. -# All Rights Reserved. -# -# Licensed under the Apache License, Version 2.0 (the "License"); you may -# not use this file except in compliance with the License. You may obtain -# a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT -# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the -# License for the specific language governing permissions and limitations -# under the License. - -""" -Import related utilities and helper functions. -""" - -import sys -import traceback - - -def import_class(import_str): - """Returns a class from a string including module and class.""" - mod_str, _sep, class_str = import_str.rpartition('.') - __import__(mod_str) - try: - return getattr(sys.modules[mod_str], class_str) - except AttributeError: - raise ImportError('Class %s cannot be found (%s)' % - (class_str, - traceback.format_exception(*sys.exc_info()))) - - -def import_object(import_str, *args, **kwargs): - """Import a class and return an instance of it.""" - return import_class(import_str)(*args, **kwargs) - - -def import_object_ns(name_space, import_str, *args, **kwargs): - """Tries to import object from default namespace. - - Imports a class and return an instance of it, first by trying - to find the class in a default namespace, then failing back to - a full path if not found in the default namespace. - """ - import_value = "%s.%s" % (name_space, import_str) - try: - return import_class(import_value)(*args, **kwargs) - except ImportError: - return import_class(import_str)(*args, **kwargs) - - -def import_module(import_str): - """Import a module.""" - __import__(import_str) - return sys.modules[import_str] - - -def import_versioned_module(version, submodule=None): - module = 'os_doc_tools.v%s' % version - if submodule: - module = '.'.join((module, submodule)) - return import_module(module) - - -def try_import(import_str, default=None): - """Try to import a module and if it fails return default.""" - try: - return import_module(import_str) - except ImportError: - return default diff --git a/os_doc_tools/openstack/common/jsonutils.py b/os_doc_tools/openstack/common/jsonutils.py deleted file mode 100644 index 8002942d..00000000 --- a/os_doc_tools/openstack/common/jsonutils.py +++ /dev/null @@ -1,190 +0,0 @@ -# Copyright 2010 United States Government as represented by the -# Administrator of the National Aeronautics and Space Administration. -# Copyright 2011 Justin Santa Barbara -# All Rights Reserved. -# -# Licensed under the Apache License, Version 2.0 (the "License"); you may -# not use this file except in compliance with the License. You may obtain -# a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT -# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the -# License for the specific language governing permissions and limitations -# under the License. - -''' -JSON related utilities. - -This module provides a few things: - - 1) A handy function for getting an object down to something that can be - JSON serialized. See to_primitive(). - - 2) Wrappers around loads() and dumps(). The dumps() wrapper will - automatically use to_primitive() for you if needed. - - 3) This sets up anyjson to use the loads() and dumps() wrappers if anyjson - is available. -''' - - -import codecs -import datetime -import functools -import inspect -import itertools -import sys - -if sys.version_info < (2, 7): - # On Python <= 2.6, json module is not C boosted, so try to use - # simplejson module if available - try: - import simplejson as json - except ImportError: - import json -else: - import json - -import six -import six.moves.xmlrpc_client as xmlrpclib - -from os_doc_tools.openstack.common import gettextutils -from os_doc_tools.openstack.common import importutils -from os_doc_tools.openstack.common import strutils -from os_doc_tools.openstack.common import timeutils - -netaddr = importutils.try_import("netaddr") - -_nasty_type_tests = [inspect.ismodule, inspect.isclass, inspect.ismethod, - inspect.isfunction, inspect.isgeneratorfunction, - inspect.isgenerator, inspect.istraceback, inspect.isframe, - inspect.iscode, inspect.isbuiltin, inspect.isroutine, - inspect.isabstract] - -_simple_types = (six.string_types + six.integer_types - + (type(None), bool, float)) - - -def to_primitive(value, convert_instances=False, convert_datetime=True, - level=0, max_depth=3): - """Convert a complex object into primitives. - - Handy for JSON serialization. We can optionally handle instances, - but since this is a recursive function, we could have cyclical - data structures. - - To handle cyclical data structures we could track the actual objects - visited in a set, but not all objects are hashable. Instead we just - track the depth of the object inspections and don't go too deep. - - Therefore, convert_instances=True is lossy ... be aware. - - """ - # handle obvious types first - order of basic types determined by running - # full tests on nova project, resulting in the following counts: - # 572754 - # 460353 - # 379632 - # 274610 - # 199918 - # 114200 - # 51817 - # 26164 - # 6491 - # 283 - # 19 - if isinstance(value, _simple_types): - return value - - if isinstance(value, datetime.datetime): - if convert_datetime: - return timeutils.strtime(value) - else: - return value - - # value of itertools.count doesn't get caught by nasty_type_tests - # and results in infinite loop when list(value) is called. - if type(value) == itertools.count: - return six.text_type(value) - - # FIXME(vish): Workaround for LP bug 852095. Without this workaround, - # tests that raise an exception in a mocked method that - # has a @wrap_exception with a notifier will fail. If - # we up the dependency to 0.5.4 (when it is released) we - # can remove this workaround. - if getattr(value, '__module__', None) == 'mox': - return 'mock' - - if level > max_depth: - return '?' - - # The try block may not be necessary after the class check above, - # but just in case ... - try: - recursive = functools.partial(to_primitive, - convert_instances=convert_instances, - convert_datetime=convert_datetime, - level=level, - max_depth=max_depth) - if isinstance(value, dict): - return dict((k, recursive(v)) for k, v in six.iteritems(value)) - elif isinstance(value, (list, tuple)): - return [recursive(lv) for lv in value] - - # It's not clear why xmlrpclib created their own DateTime type, but - # for our purposes, make it a datetime type which is explicitly - # handled - if isinstance(value, xmlrpclib.DateTime): - value = datetime.datetime(*tuple(value.timetuple())[:6]) - - if convert_datetime and isinstance(value, datetime.datetime): - return timeutils.strtime(value) - elif isinstance(value, gettextutils.Message): - return value.data - elif hasattr(value, 'iteritems'): - return recursive(dict(value.iteritems()), level=level + 1) - elif hasattr(value, '__iter__'): - return recursive(list(value)) - elif convert_instances and hasattr(value, '__dict__'): - # Likely an instance of something. Watch for cycles. - # Ignore class member vars. - return recursive(value.__dict__, level=level + 1) - elif netaddr and isinstance(value, netaddr.IPAddress): - return six.text_type(value) - else: - if any(test(value) for test in _nasty_type_tests): - return six.text_type(value) - return value - except TypeError: - # Class objects are tricky since they may define something like - # __iter__ defined but it isn't callable as list(). - return six.text_type(value) - - -def dumps(value, default=to_primitive, **kwargs): - return json.dumps(value, default=default, **kwargs) - - -def dump(obj, fp, *args, **kwargs): - return json.dump(obj, fp, *args, **kwargs) - - -def loads(s, encoding='utf-8', **kwargs): - return json.loads(strutils.safe_decode(s, encoding), **kwargs) - - -def load(fp, encoding='utf-8', **kwargs): - return json.load(codecs.getreader(encoding)(fp), **kwargs) - - -try: - import anyjson -except ImportError: - pass -else: - anyjson._modules.append((__name__, 'dumps', TypeError, - 'loads', ValueError, 'load')) - anyjson.force_implementation(__name__) diff --git a/os_doc_tools/openstack/common/local.py b/os_doc_tools/openstack/common/local.py deleted file mode 100644 index 0819d5b9..00000000 --- a/os_doc_tools/openstack/common/local.py +++ /dev/null @@ -1,45 +0,0 @@ -# Copyright 2011 OpenStack Foundation. -# All Rights Reserved. -# -# Licensed under the Apache License, Version 2.0 (the "License"); you may -# not use this file except in compliance with the License. You may obtain -# a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT -# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the -# License for the specific language governing permissions and limitations -# under the License. - -"""Local storage of variables using weak references""" - -import threading -import weakref - - -class WeakLocal(threading.local): - def __getattribute__(self, attr): - rval = super(WeakLocal, self).__getattribute__(attr) - if rval: - # NOTE(mikal): this bit is confusing. What is stored is a weak - # reference, not the value itself. We therefore need to lookup - # the weak reference and return the inner value here. - rval = rval() - return rval - - def __setattr__(self, attr, value): - value = weakref.ref(value) - return super(WeakLocal, self).__setattr__(attr, value) - - -# NOTE(mikal): the name "store" should be deprecated in the future -store = WeakLocal() - -# A "weak" store uses weak references and allows an object to fall out of scope -# when it falls out of scope in the code that uses the thread local storage. A -# "strong" store will hold a reference to the object so that it never falls out -# of scope. -weak_store = WeakLocal() -strong_store = threading.local() diff --git a/os_doc_tools/openstack/common/log.py b/os_doc_tools/openstack/common/log.py deleted file mode 100644 index 3dd34dad..00000000 --- a/os_doc_tools/openstack/common/log.py +++ /dev/null @@ -1,703 +0,0 @@ -# Copyright 2011 OpenStack Foundation. -# Copyright 2010 United States Government as represented by the -# Administrator of the National Aeronautics and Space Administration. -# All Rights Reserved. -# -# Licensed under the Apache License, Version 2.0 (the "License"); you may -# not use this file except in compliance with the License. You may obtain -# a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT -# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the -# License for the specific language governing permissions and limitations -# under the License. - -"""OpenStack logging handler. - -This module adds to logging functionality by adding the option to specify -a context object when calling the various log methods. If the context object -is not specified, default formatting is used. Additionally, an instance uuid -may be passed as part of the log message, which is intended to make it easier -for admins to find messages related to a specific instance. - -It also allows setting of formatting information through conf. - -""" - -import inspect -import itertools -import logging -import logging.config -import logging.handlers -import os -import sys -import traceback - -from oslo_config import cfg -import six -from six import moves - -_PY26 = sys.version_info[0:2] == (2, 6) - -from os_doc_tools.openstack.common.gettextutils import _ -from os_doc_tools.openstack.common import importutils -from os_doc_tools.openstack.common import jsonutils -from os_doc_tools.openstack.common import local -# NOTE(flaper87): Pls, remove when graduating this module -# from the incubator. -from os_doc_tools.openstack.common.strutils import mask_password # noqa - - -_DEFAULT_LOG_DATE_FORMAT = "%Y-%m-%d %H:%M:%S" - - -common_cli_opts = [ - cfg.BoolOpt('debug', - short='d', - default=False, - help='Print debugging output (set logging level to ' - 'DEBUG instead of default WARNING level).'), - cfg.BoolOpt('verbose', - short='v', - default=False, - help='Print more verbose output (set logging level to ' - 'INFO instead of default WARNING level).'), -] - -logging_cli_opts = [ - cfg.StrOpt('log-config-append', - metavar='PATH', - deprecated_name='log-config', - help='The name of a logging configuration file. This file ' - 'is appended to any existing logging configuration ' - 'files. For details about logging configuration files, ' - 'see the Python logging module documentation.'), - cfg.StrOpt('log-format', - metavar='FORMAT', - help='DEPRECATED. ' - 'A logging.Formatter log message format string which may ' - 'use any of the available logging.LogRecord attributes. ' - 'This option is deprecated. Please use ' - 'logging_context_format_string and ' - 'logging_default_format_string instead.'), - cfg.StrOpt('log-date-format', - default=_DEFAULT_LOG_DATE_FORMAT, - metavar='DATE_FORMAT', - help='Format string for %%(asctime)s in log records. ' - 'Default: %(default)s .'), - cfg.StrOpt('log-file', - metavar='PATH', - deprecated_name='logfile', - help='(Optional) Name of log file to output to. ' - 'If no default is set, logging will go to stdout.'), - cfg.StrOpt('log-dir', - deprecated_name='logdir', - help='(Optional) The base directory used for relative ' - '--log-file paths.'), - cfg.BoolOpt('use-syslog', - default=False, - help='Use syslog for logging. ' - 'Existing syslog format is DEPRECATED during I, ' - 'and will change in J to honor RFC5424.'), - cfg.BoolOpt('use-syslog-rfc-format', - # TODO(bogdando) remove or use True after existing - # syslog format deprecation in J - default=False, - help='(Optional) Enables or disables syslog rfc5424 format ' - 'for logging. If enabled, prefixes the MSG part of the ' - 'syslog message with APP-NAME (RFC5424). The ' - 'format without the APP-NAME is deprecated in I, ' - 'and will be removed in J.'), - cfg.StrOpt('syslog-log-facility', - default='LOG_USER', - help='Syslog facility to receive log lines.') -] - -generic_log_opts = [ - cfg.BoolOpt('use_stderr', - default=True, - help='Log output to standard error.') -] - -DEFAULT_LOG_LEVELS = ['amqp=WARN', 'amqplib=WARN', 'boto=WARN', - 'qpid=WARN', 'sqlalchemy=WARN', 'suds=INFO', - 'oslo.messaging=INFO', 'iso8601=WARN', - 'requests.packages.urllib3.connectionpool=WARN', - 'urllib3.connectionpool=WARN', 'websocket=WARN'] - -log_opts = [ - cfg.StrOpt('logging_context_format_string', - default='%(asctime)s.%(msecs)03d %(process)d %(levelname)s ' - '%(name)s [%(request_id)s %(user_identity)s] ' - '%(instance)s%(message)s', - help='Format string to use for log messages with context.'), - cfg.StrOpt('logging_default_format_string', - default='%(asctime)s.%(msecs)03d %(process)d %(levelname)s ' - '%(name)s [-] %(instance)s%(message)s', - help='Format string to use for log messages without context.'), - cfg.StrOpt('logging_debug_format_suffix', - default='%(funcName)s %(pathname)s:%(lineno)d', - help='Data to append to log format when level is DEBUG.'), - cfg.StrOpt('logging_exception_prefix', - default='%(asctime)s.%(msecs)03d %(process)d TRACE %(name)s ' - '%(instance)s', - help='Prefix each line of exception output with this format.'), - cfg.ListOpt('default_log_levels', - default=DEFAULT_LOG_LEVELS, - help='List of logger=LEVEL pairs.'), - cfg.BoolOpt('publish_errors', - default=False, - help='Enables or disables publication of error events.'), - cfg.BoolOpt('fatal_deprecations', - default=False, - help='Enables or disables fatal status of deprecations.'), - - # NOTE(mikal): there are two options here because sometimes we are handed - # a full instance (and could include more information), and other times we - # are just handed a UUID for the instance. - cfg.StrOpt('instance_format', - default='[instance: %(uuid)s] ', - help='The format for an instance that is passed with the log ' - 'message.'), - cfg.StrOpt('instance_uuid_format', - default='[instance: %(uuid)s] ', - help='The format for an instance UUID that is passed with the ' - 'log message.'), -] - -CONF = cfg.CONF -CONF.register_cli_opts(common_cli_opts) -CONF.register_cli_opts(logging_cli_opts) -CONF.register_opts(generic_log_opts) -CONF.register_opts(log_opts) - -# our new audit level -# NOTE(jkoelker) Since we synthesized an audit level, make the logging -# module aware of it so it acts like other levels. -logging.AUDIT = logging.INFO + 1 -logging.addLevelName(logging.AUDIT, 'AUDIT') - - -try: - NullHandler = logging.NullHandler -except AttributeError: # NOTE(jkoelker) NullHandler added in Python 2.7 - class NullHandler(logging.Handler): - def handle(self, record): - pass - - def emit(self, record): - pass - - def createLock(self): - self.lock = None - - -def _dictify_context(context): - if context is None: - return None - if not isinstance(context, dict) and getattr(context, 'to_dict', None): - context = context.to_dict() - return context - - -def _get_binary_name(): - return os.path.basename(inspect.stack()[-1][1]) - - -def _get_log_file_path(binary=None): - logfile = CONF.log_file - logdir = CONF.log_dir - - if logfile and not logdir: - return logfile - - if logfile and logdir: - return os.path.join(logdir, logfile) - - if logdir: - binary = binary or _get_binary_name() - return '%s.log' % (os.path.join(logdir, binary),) - - return None - - -class BaseLoggerAdapter(logging.LoggerAdapter): - - def audit(self, msg, *args, **kwargs): - self.log(logging.AUDIT, msg, *args, **kwargs) - - def isEnabledFor(self, level): - if _PY26: - # This method was added in python 2.7 (and it does the exact - # same logic, so we need to do the exact same logic so that - # python 2.6 has this capability as well). - return self.logger.isEnabledFor(level) - else: - return super(BaseLoggerAdapter, self).isEnabledFor(level) - - -class LazyAdapter(BaseLoggerAdapter): - def __init__(self, name='unknown', version='unknown'): - self._logger = None - self.extra = {} - self.name = name - self.version = version - - @property - def logger(self): - if not self._logger: - self._logger = getLogger(self.name, self.version) - if six.PY3: - # In Python 3, the code fails because the 'manager' attribute - # cannot be found when using a LoggerAdapter as the - # underlying logger. Work around this issue. - self._logger.manager = self._logger.logger.manager - return self._logger - - -class ContextAdapter(BaseLoggerAdapter): - warn = logging.LoggerAdapter.warning - - def __init__(self, logger, project_name, version_string): - self.logger = logger - self.project = project_name - self.version = version_string - self._deprecated_messages_sent = dict() - - @property - def handlers(self): - return self.logger.handlers - - def deprecated(self, msg, *args, **kwargs): - """Call this method when a deprecated feature is used. - - If the system is configured for fatal deprecations then the message - is logged at the 'critical' level and :class:`DeprecatedConfig` will - be raised. - - Otherwise, the message will be logged (once) at the 'warn' level. - - :raises: :class:`DeprecatedConfig` if the system is configured for - fatal deprecations. - - """ - stdmsg = _("Deprecated: %s") % msg - if CONF.fatal_deprecations: - self.critical(stdmsg, *args, **kwargs) - raise DeprecatedConfig(msg=stdmsg) - - # Using a list because a tuple with dict can't be stored in a set. - sent_args = self._deprecated_messages_sent.setdefault(msg, list()) - - if args in sent_args: - # Already logged this message, so don't log it again. - return - - sent_args.append(args) - self.warn(stdmsg, *args, **kwargs) - - def process(self, msg, kwargs): - # NOTE(mrodden): catch any Message/other object and - # coerce to unicode before they can get - # to the python logging and possibly - # cause string encoding trouble - if not isinstance(msg, six.string_types): - msg = six.text_type(msg) - - if 'extra' not in kwargs: - kwargs['extra'] = {} - extra = kwargs['extra'] - - context = kwargs.pop('context', None) - if not context: - context = getattr(local.store, 'context', None) - if context: - extra.update(_dictify_context(context)) - - instance = kwargs.pop('instance', None) - instance_uuid = (extra.get('instance_uuid') or - kwargs.pop('instance_uuid', None)) - instance_extra = '' - if instance: - instance_extra = CONF.instance_format % instance - elif instance_uuid: - instance_extra = (CONF.instance_uuid_format - % {'uuid': instance_uuid}) - extra['instance'] = instance_extra - - extra.setdefault('user_identity', kwargs.pop('user_identity', None)) - - extra['project'] = self.project - extra['version'] = self.version - extra['extra'] = extra.copy() - return msg, kwargs - - -class JSONFormatter(logging.Formatter): - def __init__(self, fmt=None, datefmt=None): - # NOTE(jkoelker) we ignore the fmt argument, but its still there - # since logging.config.fileConfig passes it. - self.datefmt = datefmt - - def formatException(self, ei, strip_newlines=True): - lines = traceback.format_exception(*ei) - if strip_newlines: - lines = [moves.filter( - lambda x: x, - line.rstrip().splitlines()) for line in lines] - lines = list(itertools.chain(*lines)) - return lines - - def format(self, record): - message = {'message': record.getMessage(), - 'asctime': self.formatTime(record, self.datefmt), - 'name': record.name, - 'msg': record.msg, - 'args': record.args, - 'levelname': record.levelname, - 'levelno': record.levelno, - 'pathname': record.pathname, - 'filename': record.filename, - 'module': record.module, - 'lineno': record.lineno, - 'funcname': record.funcName, - 'created': record.created, - 'msecs': record.msecs, - 'relative_created': record.relativeCreated, - 'thread': record.thread, - 'thread_name': record.threadName, - 'process_name': record.processName, - 'process': record.process, - 'traceback': None} - - if hasattr(record, 'extra'): - message['extra'] = record.extra - - if record.exc_info: - message['traceback'] = self.formatException(record.exc_info) - - return jsonutils.dumps(message) - - -def _create_logging_excepthook(product_name): - def logging_excepthook(exc_type, value, tb): - extra = {'exc_info': (exc_type, value, tb)} - getLogger(product_name).critical( - "".join(traceback.format_exception_only(exc_type, value)), - **extra) - return logging_excepthook - - -class LogConfigError(Exception): - - message = _('Error loading logging config %(log_config)s: %(err_msg)s') - - def __init__(self, log_config, err_msg): - self.log_config = log_config - self.err_msg = err_msg - - def __str__(self): - return self.message % dict(log_config=self.log_config, - err_msg=self.err_msg) - - -def _load_log_config(log_config_append): - try: - logging.config.fileConfig(log_config_append, - disable_existing_loggers=False) - except (moves.configparser.Error, KeyError) as exc: - raise LogConfigError(log_config_append, six.text_type(exc)) - - -def setup(product_name, version='unknown'): - """Setup logging.""" - if CONF.log_config_append: - _load_log_config(CONF.log_config_append) - else: - _setup_logging_from_conf(product_name, version) - sys.excepthook = _create_logging_excepthook(product_name) - - -def set_defaults(logging_context_format_string=None, - default_log_levels=None): - # Just in case the caller is not setting the - # default_log_level. This is insurance because - # we introduced the default_log_level parameter - # later in a backwards in-compatible change - if default_log_levels is not None: - cfg.set_defaults( - log_opts, - default_log_levels=default_log_levels) - if logging_context_format_string is not None: - cfg.set_defaults( - log_opts, - logging_context_format_string=logging_context_format_string) - - -def _find_facility_from_conf(): - facility_names = logging.handlers.SysLogHandler.facility_names - facility = getattr(logging.handlers.SysLogHandler, - CONF.syslog_log_facility, - None) - - if facility is None and CONF.syslog_log_facility in facility_names: - facility = facility_names.get(CONF.syslog_log_facility) - - if facility is None: - valid_facilities = facility_names.keys() - consts = ['LOG_AUTH', 'LOG_AUTHPRIV', 'LOG_CRON', 'LOG_DAEMON', - 'LOG_FTP', 'LOG_KERN', 'LOG_LPR', 'LOG_MAIL', 'LOG_NEWS', - 'LOG_AUTH', 'LOG_SYSLOG', 'LOG_USER', 'LOG_UUCP', - 'LOG_LOCAL0', 'LOG_LOCAL1', 'LOG_LOCAL2', 'LOG_LOCAL3', - 'LOG_LOCAL4', 'LOG_LOCAL5', 'LOG_LOCAL6', 'LOG_LOCAL7'] - valid_facilities.extend(consts) - raise TypeError(_('syslog facility must be one of: %s') % - ', '.join("'%s'" % fac - for fac in valid_facilities)) - - return facility - - -class RFCSysLogHandler(logging.handlers.SysLogHandler): - def __init__(self, *args, **kwargs): - self.binary_name = _get_binary_name() - # Do not use super() unless type(logging.handlers.SysLogHandler) - # is 'type' (Python 2.7). - # Use old style calls, if the type is 'classobj' (Python 2.6) - logging.handlers.SysLogHandler.__init__(self, *args, **kwargs) - - def format(self, record): - # Do not use super() unless type(logging.handlers.SysLogHandler) - # is 'type' (Python 2.7). - # Use old style calls, if the type is 'classobj' (Python 2.6) - msg = logging.handlers.SysLogHandler.format(self, record) - msg = self.binary_name + ' ' + msg - return msg - - -def _setup_logging_from_conf(project, version): - log_root = getLogger(None).logger - for handler in log_root.handlers: - log_root.removeHandler(handler) - - if CONF.use_syslog: - facility = _find_facility_from_conf() - # TODO(bogdando) use the format provided by RFCSysLogHandler - # after existing syslog format deprecation in J - if CONF.use_syslog_rfc_format: - syslog = RFCSysLogHandler(address='/dev/log', - facility=facility) - else: - syslog = logging.handlers.SysLogHandler(address='/dev/log', - facility=facility) - log_root.addHandler(syslog) - - logpath = _get_log_file_path() - if logpath: - filelog = logging.handlers.WatchedFileHandler(logpath) - log_root.addHandler(filelog) - - if CONF.use_stderr: - streamlog = ColorHandler() - log_root.addHandler(streamlog) - - elif not logpath: - # pass sys.stdout as a positional argument - # python2.6 calls the argument strm, in 2.7 it's stream - streamlog = logging.StreamHandler(sys.stdout) - log_root.addHandler(streamlog) - - if CONF.publish_errors: - try: - handler = importutils.import_object( - "os_doc_tools.openstack.common.log_handler.PublishErrorsHandler", - logging.ERROR) - except ImportError: - handler = importutils.import_object( - "oslo.messaging.notify.log_handler.PublishErrorsHandler", - logging.ERROR) - log_root.addHandler(handler) - - datefmt = CONF.log_date_format - for handler in log_root.handlers: - # NOTE(alaski): CONF.log_format overrides everything currently. This - # should be deprecated in favor of context aware formatting. - if CONF.log_format: - handler.setFormatter(logging.Formatter(fmt=CONF.log_format, - datefmt=datefmt)) - log_root.info('Deprecated: log_format is now deprecated and will ' - 'be removed in the next release') - else: - handler.setFormatter(ContextFormatter(project=project, - version=version, - datefmt=datefmt)) - - if CONF.debug: - log_root.setLevel(logging.DEBUG) - elif CONF.verbose: - log_root.setLevel(logging.INFO) - else: - log_root.setLevel(logging.WARNING) - - for pair in CONF.default_log_levels: - mod, _sep, level_name = pair.partition('=') - logger = logging.getLogger(mod) - # NOTE(AAzza) in python2.6 Logger.setLevel doesn't convert string name - # to integer code. - if sys.version_info < (2, 7): - level = logging.getLevelName(level_name) - logger.setLevel(level) - else: - logger.setLevel(level_name) - - -_loggers = {} - - -def getLogger(name='unknown', version='unknown'): - if name not in _loggers: - _loggers[name] = ContextAdapter(logging.getLogger(name), - name, - version) - return _loggers[name] - - -def getLazyLogger(name='unknown', version='unknown'): - """Returns lazy logger. - - Creates a pass-through logger that does not create the real logger - until it is really needed and delegates all calls to the real logger - once it is created. - """ - return LazyAdapter(name, version) - - -class WritableLogger(object): - """A thin wrapper that responds to `write` and logs.""" - - def __init__(self, logger, level=logging.INFO): - self.logger = logger - self.level = level - - def write(self, msg): - self.logger.log(self.level, msg.rstrip()) - - -class ContextFormatter(logging.Formatter): - """A context.RequestContext aware formatter configured through flags. - - The flags used to set format strings are: logging_context_format_string - and logging_default_format_string. You can also specify - logging_debug_format_suffix to append extra formatting if the log level is - debug. - - For information about what variables are available for the formatter see: - http://docs.python.org/library/logging.html#formatter - - If available, uses the context value stored in TLS - local.store.context - - """ - - def __init__(self, *args, **kwargs): - """Initialize ContextFormatter instance - - Takes additional keyword arguments which can be used in the message - format string. - - :keyword project: project name - :type project: string - :keyword version: project version - :type version: string - - """ - - self.project = kwargs.pop('project', 'unknown') - self.version = kwargs.pop('version', 'unknown') - - logging.Formatter.__init__(self, *args, **kwargs) - - def format(self, record): - """Uses contextstring if request_id is set, otherwise default.""" - - # store project info - record.project = self.project - record.version = self.version - - # store request info - context = getattr(local.store, 'context', None) - if context: - d = _dictify_context(context) - for k, v in d.items(): - setattr(record, k, v) - - # NOTE(sdague): default the fancier formatting params - # to an empty string so we don't throw an exception if - # they get used - for key in ('instance', 'color', 'user_identity'): - if key not in record.__dict__: - record.__dict__[key] = '' - - if record.__dict__.get('request_id'): - fmt = CONF.logging_context_format_string - else: - fmt = CONF.logging_default_format_string - - if (record.levelno == logging.DEBUG and - CONF.logging_debug_format_suffix): - fmt += " " + CONF.logging_debug_format_suffix - - if sys.version_info < (3, 2): - self._fmt = fmt - else: - self._style = logging.PercentStyle(fmt) - self._fmt = self._style._fmt - # Cache this on the record, Logger will respect our formatted copy - if record.exc_info: - record.exc_text = self.formatException(record.exc_info, record) - return logging.Formatter.format(self, record) - - def formatException(self, exc_info, record=None): - """Format exception output with CONF.logging_exception_prefix.""" - if not record: - return logging.Formatter.formatException(self, exc_info) - - stringbuffer = moves.StringIO() - traceback.print_exception(exc_info[0], exc_info[1], exc_info[2], - None, stringbuffer) - lines = stringbuffer.getvalue().split('\n') - stringbuffer.close() - - if CONF.logging_exception_prefix.find('%(asctime)') != -1: - record.asctime = self.formatTime(record, self.datefmt) - - formatted_lines = [] - for line in lines: - pl = CONF.logging_exception_prefix % record.__dict__ - fl = '%s%s' % (pl, line) - formatted_lines.append(fl) - return '\n'.join(formatted_lines) - - -class ColorHandler(logging.StreamHandler): - LEVEL_COLORS = { - logging.DEBUG: '\033[00;32m', # GREEN - logging.INFO: '\033[00;36m', # CYAN - logging.AUDIT: '\033[01;36m', # BOLD CYAN - logging.WARN: '\033[01;33m', # BOLD YELLOW - logging.ERROR: '\033[01;31m', # BOLD RED - logging.CRITICAL: '\033[01;31m', # BOLD RED - } - - def format(self, record): - record.color = self.LEVEL_COLORS[record.levelno] - return logging.StreamHandler.format(self, record) - - -class DeprecatedConfig(Exception): - message = _("Fatal call to deprecated config: %(msg)s") - - def __init__(self, msg): - super(Exception, self).__init__(self.message % dict(msg=msg)) diff --git a/os_doc_tools/openstack/common/strutils.py b/os_doc_tools/openstack/common/strutils.py deleted file mode 100644 index 979e107c..00000000 --- a/os_doc_tools/openstack/common/strutils.py +++ /dev/null @@ -1,295 +0,0 @@ -# Copyright 2011 OpenStack Foundation. -# All Rights Reserved. -# -# Licensed under the Apache License, Version 2.0 (the "License"); you may -# not use this file except in compliance with the License. You may obtain -# a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT -# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the -# License for the specific language governing permissions and limitations -# under the License. - -""" -System-level utilities and helper functions. -""" - -import math -import re -import sys -import unicodedata - -import six - -from os_doc_tools.openstack.common.gettextutils import _ - - -UNIT_PREFIX_EXPONENT = { - 'k': 1, - 'K': 1, - 'Ki': 1, - 'M': 2, - 'Mi': 2, - 'G': 3, - 'Gi': 3, - 'T': 4, - 'Ti': 4, -} -UNIT_SYSTEM_INFO = { - 'IEC': (1024, re.compile(r'(^[-+]?\d*\.?\d+)([KMGT]i?)?(b|bit|B)$')), - 'SI': (1000, re.compile(r'(^[-+]?\d*\.?\d+)([kMGT])?(b|bit|B)$')), -} - -TRUE_STRINGS = ('1', 't', 'true', 'on', 'y', 'yes') -FALSE_STRINGS = ('0', 'f', 'false', 'off', 'n', 'no') - -SLUGIFY_STRIP_RE = re.compile(r"[^\w\s-]") -SLUGIFY_HYPHENATE_RE = re.compile(r"[-\s]+") - - -# NOTE(flaper87): The following 3 globals are used by `mask_password` -_SANITIZE_KEYS = ['adminPass', 'admin_pass', 'password', 'admin_password'] - -# NOTE(ldbragst): Let's build a list of regex objects using the list of -# _SANITIZE_KEYS we already have. This way, we only have to add the new key -# to the list of _SANITIZE_KEYS and we can generate regular expressions -# for XML and JSON automatically. -_SANITIZE_PATTERNS = [] -_FORMAT_PATTERNS = [r'(%(key)s\s*[=]\s*[\"\']).*?([\"\'])', - r'(<%(key)s>).*?()', - r'([\"\']%(key)s[\"\']\s*:\s*[\"\']).*?([\"\'])', - r'([\'"].*?%(key)s[\'"]\s*:\s*u?[\'"]).*?([\'"])', - r'([\'"].*?%(key)s[\'"]\s*,\s*\'--?[A-z]+\'\s*,\s*u?[\'"])' - '.*?([\'"])', - r'(%(key)s\s*--?[A-z]+\s*)\S+(\s*)'] - -for key in _SANITIZE_KEYS: - for pattern in _FORMAT_PATTERNS: - reg_ex = re.compile(pattern % {'key': key}, re.DOTALL) - _SANITIZE_PATTERNS.append(reg_ex) - - -def int_from_bool_as_string(subject): - """Interpret a string as a boolean and return either 1 or 0. - - Any string value in: - - ('True', 'true', 'On', 'on', '1') - - is interpreted as a boolean True. - - Useful for JSON-decoded stuff and config file parsing - """ - return bool_from_string(subject) and 1 or 0 - - -def bool_from_string(subject, strict=False, default=False): - """Interpret a string as a boolean. - - A case-insensitive match is performed such that strings matching 't', - 'true', 'on', 'y', 'yes', or '1' are considered True and, when - `strict=False`, anything else returns the value specified by 'default'. - - Useful for JSON-decoded stuff and config file parsing. - - If `strict=True`, unrecognized values, including None, will raise a - ValueError which is useful when parsing values passed in from an API call. - Strings yielding False are 'f', 'false', 'off', 'n', 'no', or '0'. - """ - if not isinstance(subject, six.string_types): - subject = six.text_type(subject) - - lowered = subject.strip().lower() - - if lowered in TRUE_STRINGS: - return True - elif lowered in FALSE_STRINGS: - return False - elif strict: - acceptable = ', '.join( - "'%s'" % s for s in sorted(TRUE_STRINGS + FALSE_STRINGS)) - msg = _("Unrecognized value '%(val)s', acceptable values are:" - " %(acceptable)s") % {'val': subject, - 'acceptable': acceptable} - raise ValueError(msg) - else: - return default - - -def safe_decode(text, incoming=None, errors='strict'): - """Decodes incoming text/bytes string using `incoming` if they're not - already unicode. - - :param incoming: Text's current encoding - :param errors: Errors handling policy. See here for valid - values http://docs.python.org/2/library/codecs.html - :returns: text or a unicode `incoming` encoded - representation of it. - :raises TypeError: If text is not an instance of str - """ - if not isinstance(text, (six.string_types, six.binary_type)): - raise TypeError("%s can't be decoded" % type(text)) - - if isinstance(text, six.text_type): - return text - - if not incoming: - incoming = (sys.stdin.encoding or - sys.getdefaultencoding()) - - try: - return text.decode(incoming, errors) - except UnicodeDecodeError: - # Note(flaper87) If we get here, it means that - # sys.stdin.encoding / sys.getdefaultencoding - # didn't return a suitable encoding to decode - # text. This happens mostly when global LANG - # var is not set correctly and there's no - # default encoding. In this case, most likely - # python will use ASCII or ANSI encoders as - # default encodings but they won't be capable - # of decoding non-ASCII characters. - # - # Also, UTF-8 is being used since it's an ASCII - # extension. - return text.decode('utf-8', errors) - - -def safe_encode(text, incoming=None, - encoding='utf-8', errors='strict'): - """Encodes incoming text/bytes string using `encoding`. - - If incoming is not specified, text is expected to be encoded with - current python's default encoding. (`sys.getdefaultencoding`) - - :param incoming: Text's current encoding - :param encoding: Expected encoding for text (Default UTF-8) - :param errors: Errors handling policy. See here for valid - values http://docs.python.org/2/library/codecs.html - :returns: text or a bytestring `encoding` encoded - representation of it. - :raises TypeError: If text is not an instance of str - """ - if not isinstance(text, (six.string_types, six.binary_type)): - raise TypeError("%s can't be encoded" % type(text)) - - if not incoming: - incoming = (sys.stdin.encoding or - sys.getdefaultencoding()) - - if isinstance(text, six.text_type): - return text.encode(encoding, errors) - elif text and encoding != incoming: - # Decode text before encoding it with `encoding` - text = safe_decode(text, incoming, errors) - return text.encode(encoding, errors) - else: - return text - - -def string_to_bytes(text, unit_system='IEC', return_int=False): - """Converts a string into an float representation of bytes. - - The units supported for IEC :: - - Kb(it), Kib(it), Mb(it), Mib(it), Gb(it), Gib(it), Tb(it), Tib(it) - KB, KiB, MB, MiB, GB, GiB, TB, TiB - - The units supported for SI :: - - kb(it), Mb(it), Gb(it), Tb(it) - kB, MB, GB, TB - - Note that the SI unit system does not support capital letter 'K' - - :param text: String input for bytes size conversion. - :param unit_system: Unit system for byte size conversion. - :param return_int: If True, returns integer representation of text - in bytes. (default: decimal) - :returns: Numerical representation of text in bytes. - :raises ValueError: If text has an invalid value. - - """ - try: - base, reg_ex = UNIT_SYSTEM_INFO[unit_system] - except KeyError: - msg = _('Invalid unit system: "%s"') % unit_system - raise ValueError(msg) - match = reg_ex.match(text) - if match: - magnitude = float(match.group(1)) - unit_prefix = match.group(2) - if match.group(3) in ['b', 'bit']: - magnitude /= 8 - else: - msg = _('Invalid string format: %s') % text - raise ValueError(msg) - if not unit_prefix: - res = magnitude - else: - res = magnitude * pow(base, UNIT_PREFIX_EXPONENT[unit_prefix]) - if return_int: - return int(math.ceil(res)) - return res - - -def to_slug(value, incoming=None, errors="strict"): - """Normalize string. - - Convert to lowercase, remove non-word characters, and convert spaces - to hyphens. - - Inspired by Django's `slugify` filter. - - :param value: Text to slugify - :param incoming: Text's current encoding - :param errors: Errors handling policy. See here for valid - values http://docs.python.org/2/library/codecs.html - :returns: slugified unicode representation of `value` - :raises TypeError: If text is not an instance of str - """ - value = safe_decode(value, incoming, errors) - # NOTE(aababilov): no need to use safe_(encode|decode) here: - # encodings are always "ascii", error handling is always "ignore" - # and types are always known (first: unicode; second: str) - value = unicodedata.normalize("NFKD", value).encode( - "ascii", "ignore").decode("ascii") - value = SLUGIFY_STRIP_RE.sub("", value).strip().lower() - return SLUGIFY_HYPHENATE_RE.sub("-", value) - - -def mask_password(message, secret="***"): - """Replace password with 'secret' in message. - - :param message: The string which includes security information. - :param secret: value with which to replace passwords. - :returns: The unicode value of message with the password fields masked. - - For example: - - >>> mask_password("'adminPass' : 'aaaaa'") - "'adminPass' : '***'" - >>> mask_password("'admin_pass' : 'aaaaa'") - "'admin_pass' : '***'" - >>> mask_password('"password" : "aaaaa"') - '"password" : "***"' - >>> mask_password("'original_password' : 'aaaaa'") - "'original_password' : '***'" - >>> mask_password("u'original_password' : u'aaaaa'") - "u'original_password' : u'***'" - """ - message = six.text_type(message) - - # NOTE(ldbragst): Check to see if anything in message contains any key - # specified in _SANITIZE_KEYS, if not then just return the message since - # we don't have to mask any passwords. - if not any(key in message for key in _SANITIZE_KEYS): - return message - - secret = r'\g<1>' + secret + r'\g<2>' - for pattern in _SANITIZE_PATTERNS: - message = re.sub(pattern, secret, message) - return message diff --git a/os_doc_tools/openstack/common/timeutils.py b/os_doc_tools/openstack/common/timeutils.py deleted file mode 100644 index c48da95f..00000000 --- a/os_doc_tools/openstack/common/timeutils.py +++ /dev/null @@ -1,210 +0,0 @@ -# Copyright 2011 OpenStack Foundation. -# All Rights Reserved. -# -# Licensed under the Apache License, Version 2.0 (the "License"); you may -# not use this file except in compliance with the License. You may obtain -# a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT -# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the -# License for the specific language governing permissions and limitations -# under the License. - -""" -Time related utilities and helper functions. -""" - -import calendar -import datetime -import time - -import iso8601 -import six - - -# ISO 8601 extended time format with microseconds -_ISO8601_TIME_FORMAT_SUBSECOND = '%Y-%m-%dT%H:%M:%S.%f' -_ISO8601_TIME_FORMAT = '%Y-%m-%dT%H:%M:%S' -PERFECT_TIME_FORMAT = _ISO8601_TIME_FORMAT_SUBSECOND - - -def isotime(at=None, subsecond=False): - """Stringify time in ISO 8601 format.""" - if not at: - at = utcnow() - st = at.strftime(_ISO8601_TIME_FORMAT - if not subsecond - else _ISO8601_TIME_FORMAT_SUBSECOND) - tz = at.tzinfo.tzname(None) if at.tzinfo else 'UTC' - st += ('Z' if tz == 'UTC' else tz) - return st - - -def parse_isotime(timestr): - """Parse time from ISO 8601 format.""" - try: - return iso8601.parse_date(timestr) - except iso8601.ParseError as e: - raise ValueError(six.text_type(e)) - except TypeError as e: - raise ValueError(six.text_type(e)) - - -def strtime(at=None, fmt=PERFECT_TIME_FORMAT): - """Returns formatted utcnow.""" - if not at: - at = utcnow() - return at.strftime(fmt) - - -def parse_strtime(timestr, fmt=PERFECT_TIME_FORMAT): - """Turn a formatted time back into a datetime.""" - return datetime.datetime.strptime(timestr, fmt) - - -def normalize_time(timestamp): - """Normalize time in arbitrary timezone to UTC naive object.""" - offset = timestamp.utcoffset() - if offset is None: - return timestamp - return timestamp.replace(tzinfo=None) - offset - - -def is_older_than(before, seconds): - """Return True if before is older than seconds.""" - if isinstance(before, six.string_types): - before = parse_strtime(before).replace(tzinfo=None) - else: - before = before.replace(tzinfo=None) - - return utcnow() - before > datetime.timedelta(seconds=seconds) - - -def is_newer_than(after, seconds): - """Return True if after is newer than seconds.""" - if isinstance(after, six.string_types): - after = parse_strtime(after).replace(tzinfo=None) - else: - after = after.replace(tzinfo=None) - - return after - utcnow() > datetime.timedelta(seconds=seconds) - - -def utcnow_ts(): - """Timestamp version of our utcnow function.""" - if utcnow.override_time is None: - # NOTE(kgriffs): This is several times faster - # than going through calendar.timegm(...) - return int(time.time()) - - return calendar.timegm(utcnow().timetuple()) - - -def utcnow(): - """Overridable version of utils.utcnow.""" - if utcnow.override_time: - try: - return utcnow.override_time.pop(0) - except AttributeError: - return utcnow.override_time - return datetime.datetime.utcnow() - - -def iso8601_from_timestamp(timestamp): - """Returns an iso8601 formatted date from timestamp.""" - return isotime(datetime.datetime.utcfromtimestamp(timestamp)) - - -utcnow.override_time = None - - -def set_time_override(override_time=None): - """Overrides utils.utcnow. - - Make it return a constant time or a list thereof, one at a time. - - :param override_time: datetime instance or list thereof. If not - given, defaults to the current UTC time. - """ - utcnow.override_time = override_time or datetime.datetime.utcnow() - - -def advance_time_delta(timedelta): - """Advance overridden time using a datetime.timedelta.""" - assert utcnow.override_time is not None - try: - for dt in utcnow.override_time: - dt += timedelta - except TypeError: - utcnow.override_time += timedelta - - -def advance_time_seconds(seconds): - """Advance overridden time by seconds.""" - advance_time_delta(datetime.timedelta(0, seconds)) - - -def clear_time_override(): - """Remove the overridden time.""" - utcnow.override_time = None - - -def marshall_now(now=None): - """Make an rpc-safe datetime with microseconds. - - Note: tzinfo is stripped, but not required for relative times. - """ - if not now: - now = utcnow() - return dict(day=now.day, month=now.month, year=now.year, hour=now.hour, - minute=now.minute, second=now.second, - microsecond=now.microsecond) - - -def unmarshall_time(tyme): - """Unmarshall a datetime dict.""" - return datetime.datetime(day=tyme['day'], - month=tyme['month'], - year=tyme['year'], - hour=tyme['hour'], - minute=tyme['minute'], - second=tyme['second'], - microsecond=tyme['microsecond']) - - -def delta_seconds(before, after): - """Return the difference between two timing objects. - - Compute the difference in seconds between two date, time, or - datetime objects (as a float, to microsecond resolution). - """ - delta = after - before - return total_seconds(delta) - - -def total_seconds(delta): - """Return the total seconds of datetime.timedelta object. - - Compute total seconds of datetime.timedelta, datetime.timedelta - doesn't have method total_seconds in Python2.6, calculate it manually. - """ - try: - return delta.total_seconds() - except AttributeError: - return ((delta.days * 24 * 3600) + delta.seconds + - float(delta.microseconds) / (10 ** 6)) - - -def is_soon(dt, window): - """Determines if time is going to happen in the next window seconds. - - :param dt: the time - :param window: minimum seconds to remain to consider the time not soon - - :return: True if expiration is within the given duration - """ - soon = (utcnow() + datetime.timedelta(seconds=window)) - return normalize_time(dt) <= soon diff --git a/os_doc_tools/resources/README.rst b/os_doc_tools/resources/README.rst deleted file mode 100644 index 6a6b1d39..00000000 --- a/os_doc_tools/resources/README.rst +++ /dev/null @@ -1,8 +0,0 @@ -These files are copied from the following locations: - - * docbookxi.rng: http://docbook.org/xml/5.1CR1/rng/docbookxi.rng - * extensions.rng: https://raw.githubusercontent.com/openstack/clouddocs-maven-plugin/master/src/main/resources/rng/extensions.rng - * rackbook.rng: https://raw.githubusercontent.com/openstack/clouddocs-maven-plugin/master/src/main/resources/rng/rackbook.rng - * wadl.rng: https://raw.githubusercontent.com/openstack/clouddocs-maven-plugin/master/src/main/resources/rng/wadl.rng - * wadl.xsd: http://docs.rackspace.com/rackbook/wadl.xsd - * xml.xsd: http://docs.rackspace.com/rackbook/xml.xsd diff --git a/os_doc_tools/resources/docbookxi.rng b/os_doc_tools/resources/docbookxi.rng deleted file mode 100644 index ba00d930..00000000 --- a/os_doc_tools/resources/docbookxi.rng +++ /dev/null @@ -1,18590 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - Any attribute, including any attribute in any namespace. - - - - - - - Any element from almost any namespace - - - - - - - - - - - - - - - -
- - - - Designates the computer or chip architecture to which the element applies - - - - - - Designates the intended audience to which the element applies, for example, system administrators, programmers, or new users. - - - - - - provides a standard place for application-specific effectivity - - - - - - Indicates standards conformance characteristics of the element - - - - - - Indicates the operating system to which the element is applicable - - - - - - Indicates the editorial revision to which the element belongs - - - - - - Indicates something about the security level associated with the element to which it applies - - - - - - Indicates the level of user experience for which the element applies - - - - - - Indicates the computer vendor to which the element applies. - - - - - - Indicates the word size (width in bits) of the computer architecture to which the element applies - - - - - - Indicates the output format (for example, print or epub) to which the element applies - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Points to the element whose content is to be used as the text of the link - - - - - - - Points to an internal link target by identifying the value of its xml:id attribute - - - - - - - Points to one or more internal link targets by identifying the value of their xml:id attributes - - - - - - - Identifies a link target with a URI - - - - - - - Identifies the XLink link type - simple - An XLink simple link type - - - - - - Identifies the XLink role of the link - - - - - - - Identifies the XLink arcrole of the link - - - - - - - Identifies the XLink title of the link - - - - - - new - An application traversing to the ending resource should load it in a new window, frame, pane, or other relevant presentation context. - replace - An application traversing to the ending resource should load the resource in the same window, frame, pane, or other relevant presentation context in which the starting resource was loaded. - embed - An application traversing to the ending resource should load its presentation in place of the presentation of the starting resource. - other - The behavior of an application traversing to the ending resource is unconstrained by XLink. The application should look for other markup present in the link to determine the appropriate behavior. - none - The behavior of an application traversing to the ending resource is unconstrained by this specification. No other markup is present to help the application determine the appropriate behavior. - - - - - - Identifies the XLink show behavior of the link - - - - - - - onLoad - An application should traverse to the ending resource immediately on loading the starting resource. - onRequest - An application should traverse from the starting resource to the ending resource only on a post-loading event triggered for the purpose of traversal. - other - The behavior of an application traversing to the ending resource is unconstrained by this specification. The application should look for other markup present in the link to determine the appropriate behavior. - none - The behavior of an application traversing to the ending resource is unconstrained by this specification. No other markup is present to help the application determine the appropriate behavior. - - - - - - Identifies the XLink actuate behavior of the link - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Identifies the unique ID value of the element - - - - - - - Specifies the DocBook version of the element and its descendants - - - - - - Specifies the natural language of the element and its descendants - - - - - - Specifies the base URI of the element and its descendants - - - - - - - Provides the name or similar semantic identifier assigned to the content in some previous markup scheme - - - - - - Provides the text that is to be generated for a cross reference to the element - - - - - - Specifies a keyword or keywords identifying additional style information - - - - - - changed - The element has been changed. - added - The element is new (has been added to the document). - deleted - The element has been deleted. - off - Explicitly turns off revision markup for this element. - - - - - - Identifies the revision status of the element - - - - - - - ltr - Left-to-right text - rtl - Right-to-left text - lro - Left-to-right override - rlo - Right-to-left override - - - - - - Identifies the direction of text in an element - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Specifies the format of the data - - - - - Indentifies the location of the data by URI - - - - Identifies the location of the data by external identifier (entity name) - - - - - - - - continues - Line numbering continues from the immediately preceding element with the same name. - restarts - Line numbering restarts (begins at 1, usually). - - - - - - Determines whether line numbering continues from the previous element or restarts. - - - - - - - numbered - Lines are numbered. - unnumbered - Lines are not numbered. - - - - - - Determines whether lines are numbered. - - - - - - - Specifies the initial line number. - - - - - - - Identifies the language (i.e. programming language) of the verbatim content. - - - - - - Can be used to indicate explicitly that whitespace in the verbatim environment is preserved. Whitespace must always be preserved in verbatim environments whether this attribute is specified or not. - preserve - Whitespace must be preserved. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Specifies an identifying string for presentation purposes - - - - - - Specifies the width (in characters) of the element - - - - - - - compact - The spacing should be "compact". - normal - The spacing should be "normal". - - - - - - Specifies (a hint about) the spacing of the content - - - - - - - 0 - The element should be rendered in the current text flow (with the flow column width). - 1 - The element should be rendered across the full text page. - - - - - - Indicates if the element is rendered across the column or the page - - - - - - - Identifies the language (i.e. programming language) of the content. - - - - - - optional - The content describes an optional step or steps. - required - The content describes a required step or steps. - - - - - - Specifies if the content is required or optional. - - - - - - - Specifies style information to be used when rendering the float - - - - - - Specifies the width of the element - - - - - - Specifies the depth of the element - - - - - - Specifies the width of the content rectangle - - - - - - Specifies the depth of the content rectangle - - - - - - 0 - False (do not scale-to-fit; anamorphic scaling may occur) - 1 - True (scale-to-fit; anamorphic scaling is forbidden) - - - - - - Specifies the scaling factor - - - - - - - Specifies a classid for a media object player - - - - - - Specifies the autoplay setting for a media object player - - - - - - center - Centered horizontally - char - Aligned horizontally on the specified character - justify - Fully justified (left and right margins or edges) - left - Left aligned - right - Right aligned - - - - - - bottom - Aligned on the bottom of the region - middle - Centered vertically - top - Aligned on the top of the region - - - - - - doi - A digital object identifier. - isbn - An international standard book number. - isrn - An international standard technical report number (ISO 10444). - issn - An international standard serial number. - istc - An international standard text code. - libraryofcongress - A Library of Congress reference number. - pubsnumber - A publication number (an internal number or possibly organizational standard). - uri - A Uniform Resource Identifier - - - - - - - Identifies the kind of bibliographic identifier - - - - - - - - Identifies the nature of the non-standard bibliographic identifier - - - - - - - - Identifies the kind of bibliographic identifier - other - Indicates that the identifier is some 'other' kind. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - - - - - - - - - - - - - - - The text of the title of a section of a document or of a formal block-level element - - - - - - -
- -
- - - - - - - - - - - - - - - - - The abbreviation of a title - - - - - - -
- -
- - - - - - - - - - - - - - - - - The subtitle of a document - - - - - - -
- -
- - - - - - - - - - - - - - - - A wrapper for information about a component or other block - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - A wrapper for information about a component or other block with a required title - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - A wrapper for information about a component or other block with only a title - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - A wrapper for information about a component or other block with only a required title - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - A wrapper for information about a component or other block without a title - - - - - - -
- -
- - - - - - - Identifies the controlled vocabulary used by this set's terms - - - - - - - - - - - - - - - - - - - - A set of terms describing the subject matter of a document - - - - - - -
- -
- - - - - - - Specifies a ranking for this subject relative to other subjects in the same set - - - - - - - - - - - - - - - - - - - One of a group of terms describing the subject matter of a document - - - - - - -
- -
- - - - - - - - - - - - - - - - - A term in a group of terms describing the subject matter of a document - - - - -
- -
- - - - - - - - - - - - - - - - - A set of keywords describing the content of a document - - - - - - -
- -
- - - - - - - - - - - - - - - - - One of a set of keywords describing the content of a document - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - - -
- - - - - - - - - - - - - - - - - - - - - A list of operations to be performed in a well-defined sequence - - - If this element is the root element, it must have a version attribute. - - - - - - - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - - - - - - - - A unit of action in a procedure - - - If this element is the root element, it must have a version attribute. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - - - - - - - - Alternative steps in a procedure - - - If this element is the root element, it must have a version attribute. - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - - - - A wrapper for steps that occur within steps in a procedure - - - - - - -
- -
- - - - - - - - - - - - - - - - - A wrapper for identifying the results of a procedure or step - - - - - - -
- -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - A portion of a document that is isolated from the main narrative flow - - - sidebar must not occur among the children or descendants of sidebar - - - - - If this element is the root element, it must have a version attribute. - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - - - - - A summary - - - If this element is the root element, it must have a version attribute. - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - - - - - A short description or note about a person - - - If this element is the root element, it must have a version attribute. - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - - - - - A quotation set off from the main text - - - If this element is the root element, it must have a version attribute. - - - - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - The source of a block quote or epigraph - - - - - - - - - - - - -
- -
- - - sect1 - Render as a first-level section - sect2 - Render as a second-level section - sect3 - Render as a third-level section - sect4 - Render as a fourth-level section - sect5 - Render as a fifth-level section - - - - - - - Indicates how the bridge head should be rendered - - - - - - - - Identifies the nature of the non-standard rendering - - - - - - - - Indicates how the bridge head should be rendered - other - Identifies a non-standard rendering - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - A free-floating heading - - - - - - -
- -
- - - - - - - - - - - - - - - - - A remark (or comment) intended for presentation in a draft manuscript - - - - - - -
- -
- - - - - - - - - - - - - - - - - - - - - A short inscription at the beginning of a document or component - - - If this element is the root element, it must have a version attribute. - - - - - - - - - - - - - - - -
- -
- - - - - - - Identifies the desired footnote mark - - - - - - - - - - - - - - - - - - - - A footnote - - - footnote must not occur among the children or descendants of footnote - - - - - example must not occur among the children or descendants of footnote - - - - - figure must not occur among the children or descendants of footnote - - - - - table must not occur among the children or descendants of footnote - - - - - equation must not occur among the children or descendants of footnote - - - - - sidebar must not occur among the children or descendants of footnote - - - - - task must not occur among the children or descendants of footnote - - - - - epigraph must not occur among the children or descendants of footnote - - - - - caution must not occur among the children or descendants of footnote - - - - - important must not occur among the children or descendants of footnote - - - - - note must not occur among the children or descendants of footnote - - - - - tip must not occur among the children or descendants of footnote - - - - - warning must not occur among the children or descendants of footnote - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - - - - - A paragraph with a title - - - If this element is the root element, it must have a version attribute. - - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - - - - - A paragraph - - - If this element is the root element, it must have a version attribute. - - - - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - - - - - A paragraph that contains only text and inline markup, no block elements - - - If this element is the root element, it must have a version attribute. - - - - - - - - - -
- -
- - - - - - - Identifies the type of mark to be used on items in this list - - - - - - - - - - - - - - - - - - - - - - - - - - - A list in which each entry is marked with a bullet or other dingbat - - - If this element is the root element, it must have a version attribute. - - - - - - - - - - - - -
- -
- - - - - - - continues - Specifies that numbering should begin where the preceding list left off - restarts - Specifies that numbering should begin again at 1 - - - - - - Indicates how list numbering should begin relative to the immediately preceding list - - - - - - - Specifies the initial line number. - - - - - - - ignore - Specifies that numbering should ignore list nesting - inherit - Specifies that numbering should inherit from outer-level lists - - - - - - Indicates whether or not item numbering should be influenced by list nesting - - - - - - - arabic - Specifies Arabic numeration (1, 2, 3, …) - upperalpha - Specifies upper-case alphabetic numeration (A, B, C, …) - loweralpha - Specifies lower-case alphabetic numeration (a, b, c, …) - upperroman - Specifies upper-case Roman numeration (I, II, III, …) - lowerroman - Specifies lower-case Roman numeration (i, ii, iii …) - - - - - - Indicates the desired numeration - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - A list in which each entry is marked with a sequentially incremented label - - - If this element is the root element, it must have a version attribute. - - - - - - - - - - - - -
- -
- - - - - - - Specifies the keyword for the type of mark that should be used on this - item, instead of the mark that would be used by default - - - - - - - - - - - - - - - - - - - - A wrapper for the elements of a list item - - - - - - -
- -
- - - - - - - - - - - - - - - - - - - - - A segmented list, a list of sets of elements - - - If this element is the root element, it must have a version attribute. - - - - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - The title of an element of a list item in a segmented list - - - - - - -
- -
- - - - - - - - - - - - - - - - - A list item in a segmented list - - - The number of seg elements must be the same as the number of segtitle elements in the parent segmentedlist - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - An element of a list item in a segmented list - - - - - - -
- -
- - - - - - - horiz - A tabular presentation in row-major order. - vert - A tabular presentation in column-major order. - inline - An inline presentation, usually a comma-delimited list. - - - - - - Specifies the type of list presentation. - - - - - - - Specifies the number of columns for horizontal or vertical presentation - - - - - - - - - - - - - - - - - - - - - - - An undecorated list of single words or short phrases - - - If this element is the root element, it must have a version attribute. - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - An element of a simple list - - - - - - -
- -
- - - - - - - Indicates a length beyond which the presentation system may consider a term too long and select an alternate presentation for that term, item, or list - - - - - - - - - - - - - - - - - - - - - - - - - - A list in which each entry is composed of a set of one or more terms and an associated description - - - If this element is the root element, it must have a version attribute. - - - - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - A wrapper for a set of terms and the associated description in a variable list - - - - - - - -
- -
- - - - - - - - - - - - - - - - - The word or phrase being defined or described in a variable list - - - - - - -
- -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - A formal example, with a title - - - example must not occur among the children or descendants of example - - - - - figure must not occur among the children or descendants of example - - - - - table must not occur among the children or descendants of example - - - - - equation must not occur among the children or descendants of example - - - - - If this element is the root element, it must have a version attribute. - - - - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - A displayed example without a title - - - If this element is the root element, it must have a version attribute. - - - - - - - - - - - - -
- - - - - - - - - - - - - - - - - - - - - -
- - - - - - - monospaced - The literal layout should be formatted with a monospaced font - normal - The literal layout should be formatted with the current font - - - - - - Specifies the class of literal layout - - - - - - - - - - - - - - - - - - - - - A block of text in which line breaks and white space are to be reproduced faithfully - - - If this element is the root element, it must have a version attribute. - - - - - - -
- -
- - - - - - - - - - - - - - - - - - - - - - - - - Text that a user sees or might see on a computer screen - - - If this element is the root element, it must have a version attribute. - - - - - - -
- -
- - - - - - - - - - - - - - - - - - - - - A representation of what the user sees or might see on a computer screen - - - If this element is the root element, it must have a version attribute. - - - - - - - -
- -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - A formal figure, generally an illustration, with a title - - - example must not occur among the children or descendants of figure - - - - - figure must not occur among the children or descendants of figure - - - - - table must not occur among the children or descendants of figure - - - - - equation must not occur among the children or descendants of figure - - - - - If this element is the root element, it must have a version attribute. - - - - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - A untitled figure - - - If this element is the root element, it must have a version attribute. - - - - - - - - - - - - -
- - - - - - - - - - - - - -
- - - - - - - - - - - - - - - - - - - - - A displayed media object (video, audio, image, etc.) - - - If this element is the root element, it must have a version attribute. - - - - - - - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - - - - - An inline media object (video, audio, image, and so on) - - - If this element is the root element, it must have a version attribute. - - - - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - - - - - A wrapper for video data and its associated meta-information - - - If this element is the root element, it must have a version attribute. - - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - - - - - A wrapper for audio data and its associated meta-information - - - If this element is the root element, it must have a version attribute. - - - - - - - - - - -
- - - - - - - - - - -
- - - - - - - - - - - - - - - - - - - - - A wrapper for image data and its associated meta-information - - - If this element is the root element, it must have a version attribute. - - - - - - - -
- -
- - - - - - - - - - - - - - - - - - - - - A wrapper for a text description of an object and its associated meta-information - - - If this element is the root element, it must have a version attribute. - - - - - - - - - - - - - -
- -
- - - - - - - - - - - Specifies the (horizontal) alignment of the video data - - - - - - - - - - - - - - - - - - - Specifies the vertical alignment of the video data - - - - - - - - - - - - - - - - - - - - - - - - - - - Determines if anamorphic scaling is forbidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Pointer to external video data - - - If this element is the root element, it must have a version attribute. - - - - - - -
- -
- - - - - - - - - - - Specifies the (horizontal) alignment of the video data - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Determines if anamorphic scaling is forbidden - - - - - - - - - - - Specifies the vertical alignment of the video data - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Pointer to external audio data - - - If this element is the root element, it must have a version attribute. - - - - - - -
- -
- - - - - - - - - - - Specifies the (horizontal) alignment of the image data - - - - - - - - - - - Specifies the vertical alignment of the image data - - - - - - - - - - - - - - - - - - - - - - - - - - - Determines if anamorphic scaling is forbidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Pointer to external image data - - - If this element is the root element, it must have a version attribute. - - - - - - -
- -
- - - - - - - Identifies the encoding of the text in the external file - - - - - - - - - - - - - - - - - - - - - - - Pointer to external text data - - - If this element is the root element, it must have a version attribute. - - - - - - -
- -
- - - - - - - Specifies the name of the parameter - - - - - - Specifies the value of the parameter - - - - - - Specifies the type of the value of the parameter - - - - - - - - - - - - - - - - - - - - Application specific parameters for a media player - - - - -
- -
- - - - - - - - - - - - - - - - - - - - - A caption - - - example must not occur among the children or descendants of caption - - - - - figure must not occur among the children or descendants of caption - - - - - table must not occur among the children or descendants of caption - - - - - equation must not occur among the children or descendants of caption - - - - - sidebar must not occur among the children or descendants of caption - - - - - task must not occur among the children or descendants of caption - - - - - caution must not occur among the children or descendants of caption - - - - - important must not occur among the children or descendants of caption - - - - - note must not occur among the children or descendants of caption - - - - - tip must not occur among the children or descendants of caption - - - - - warning must not occur among the children or descendants of caption - - - - - If this element is the root element, it must have a version attribute. - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - - A real-world address, generally a postal address - - - If this element is the root element, it must have a version attribute. - - - - - - - - - - - - - - - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - A street address in an address - - - - -
- -
- - - - - - - - - - - - - - - - - A post office box in an address - - - - -
- -
- - - - - - - - - - - - - - - - - A postal code in an address - - - - -
- -
- - - - - - - - - - - - - - - - - The name of a city in an address - - - - -
- -
- - - - - - - - - - - - - - - - - A state or province in an address - - - - -
- -
- - - - - - - - - - - - - - - - - The name of a country - - - - -
- -
- - - - - - - - - - - - - - - - - A telephone number - - - - -
- -
- - - - - - - - - - - - - - - - - A fax number - - - - -
- -
- - - - - - - - - - - - - - - - - Uncategorized information in address - - - - -
- -
- - - - - - - - - - - - - - - - - The institutional affiliation of an individual - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - A brief description of an affiliation - - - - -
- -
- - - - - - - - - - - - - - - - - The title of an individual in an organization - - - - -
- -
- - - consortium - A consortium - corporation - A corporation - informal - An informal organization - nonprofit - A non-profit organization - - - - - - Specifies the nature of the organization - - - - - - - Specifies the nature of the organization - other - Indicates a non-standard organization class - - - Identifies the non-standard nature of the organization - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - The name of an organization - - - - -
- -
- - - - - - - - - - - - - - - - - A division of an organization - - - - - - -
- -
- - - - - - - - - - - - - - - - - The page numbers of an article as published - - - - -
- -
- - - - - - - - - - - - - - - - - The personal name of an individual - - - - - - - - - - - - - - - - - - - - - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - - - - - - - - - - - - - - - The name of an individual author - - - - -
- -
- - - - - - - - - - - - - - - - - Wrapper for author information when a document has multiple authors or collaborators - - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - Identifies a collaborator - - - - - - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - The initials or other short identifier for an author - - - - -
- -
- - - - - - - - - - - - - - - - - A person and associated metadata - - - - - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - An organization and associated metadata - - - - - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - A wrapper for document meta-information about a conference - - - - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - The dates of a conference for which a document was written - - - - -
- -
- - - - - - - - - - - - - - - - - The title of a conference for which a document was written - - - - -
- -
- - - - - - - - - - - - - - - - - An identifier, frequently numerical, associated with a conference for which a document was written - - - - -
- -
- - - - - - - - - - - - - - - - - The sponsor of a conference for which a document was written - - - - -
- -
- - - - - - - - - - - - - - - - - The contract number of a document - - - - -
- -
- - - - - - - - - - - - - - - - - The sponsor of a contract - - - - -
- -
- - - - - - - - - - - - - - - - - Copyright information about a document - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - The year of publication of a document - - - - -
- -
- - - - - - - - - - - - - - - - - The name of the individual or organization that holds a copyright - - - - -
- - - - - - - - - - - - - - - - - - - - -
- - - - - - - - - - - - - - - - - Additional content for the cover of a publication - - - - - - -
- - - - - - - - - - - -
- - - - - - - - - - - - - - - - - The date of publication or revision of a document - - - - -
- -
- - - - - - - - - - - - - - - - - The name or number of an edition of a document - - - - -
- -
- - - - - - - - - - - - - - - - - The name of the editor of a document - - - - -
- -
- - - - - - - - - - - - - - - - - - An identifier for a document - - - - -
- -
- - - - - - - - - - - - - - - - - - A citation of a bibliographic identifier - - - - -
- -
- - - - - - - - - - - - - - - - - - The source of a document - - - - -
- -
- - - hasformat - The described resource pre-existed the referenced resource, which is essentially the same intellectual content presented in another format - haspart - The described resource includes the referenced resource either physically or logically - hasversion - The described resource has a version, edition, or adaptation, namely, the referenced resource - isformatof - The described resource is the same intellectual content of the referenced resource, but presented in another format - ispartof - The described resource is a physical or logical part of the referenced resource - isreferencedby - The described resource is referenced, cited, or otherwise pointed to by the referenced resource - isreplacedby - The described resource is supplanted, displaced, or superceded by the referenced resource - isrequiredby - The described resource is required by the referenced resource, either physically or logically - isversionof - The described resource is a version, edition, or adaptation of the referenced resource; changes in version imply substantive changes in content rather than differences in format - references - The described resource references, cites, or otherwise points to the referenced resource - replaces - The described resource supplants, displaces, or supersedes the referenced resource - requires - The described resource requires the referenced resource to support its function, delivery, or coherence of content - - - - - - - Identifies the type of relationship - - - - - - - - - Identifies the type of relationship - othertype - The described resource has a non-standard relationship with the referenced resource - - - - A keyword that identififes the type of the non-standard relationship - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - The relationship of a document to another - - - - -
- -
- - - dcmipoint - The DCMI Point identifies a point in space using its geographic coordinates - iso3166 - ISO 3166 Codes for the representation of names of countries - dcmibox - The DCMI Box identifies a region of space using its geographic limits - tgn - The Getty Thesaurus of Geographic Names - - - - - - - Specifies the type of spatial coverage - - - - - - - - - Specifies the type of spatial coverage - otherspatial - Identifies a non-standard type of coverage - - - - A keyword that identifies the type of non-standard coverage - - - - - - - - - - - - - - dcmiperiod - A specification of the limits of a time interval - w3c-dtf - W3C Encoding rules for dates and times—a profile based on ISO 8601 - - - - - - - Specifies the type of temporal coverage - - - - - - - - - Specifies the type of temporal coverage - othertemporal - Specifies a non-standard type of coverage - - - - A keyword that identifies the type of non-standard coverage - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - The spatial or temporal coverage of a document - - - - -
- -
- - - - - - - - - - - - - - - - - - - - - A statement of legal obligations or requirements - - - If this element is the root element, it must have a version attribute. - - - - - - - - - -
- -
- - - copyeditor - A copy editor - graphicdesigner - A graphic designer - productioneditor - A production editor - technicaleditor - A technical editor - translator - A translator - indexer - An indexer - proofreader - A proof-reader - coverdesigner - A cover designer - interiordesigner - An interior designer - illustrator - An illustrator - reviewer - A reviewer - typesetter - A typesetter - conversion - A converter (a persons responsible for conversion, not an application) - - - - - - - Identifies the nature of the contributor - - - - - - - - Identifies the nature of the non-standard contribution - - - - - - - - Identifies the nature of the contributor - other - Identifies a non-standard contribution - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - A person or entity, other than an author or editor, credited in a document - - - - -
- -
- - - - - - - - - - - - - - - - - The numbers of the pages in a book, for use in a bibliographic entry - - - - -
- -
- - - - - - - - - - - - - - - - - A summary of the contributions made to a document by a credited source - - - - - - -
- -
- - - - - - - - - - - - - - - - - The title of a person - - - - -
- -
- - - - - - - - - - - - - - - - - A given name of a person - - - - -
- -
- - - - - - - - - - - - - - - - - The given name of a person - - - - -
- -
- - - - - - - - - - - - - - - - - An inherited or family name; in western cultures the last name - - - - -
- -
- - - - - - - - - - - - - - - - - The portion of a person's name indicating a relationship to ancestors - - - - -
- -
- - - - - - - - - - - - - - - - - A component of a person's name that is not a first name, surname, or lineage - - - - -
- -
- - - - - - - - - - - - - - - - - The printing history of a document - - - - - - -
- -
- - - - - - - - - - - - - - - - - The date of publication of a document - - - - -
- -
- - - - - - - - - - - - - - - - - The publisher of a document - - - - - - - -
- -
- - - - - - - - - - - - - - - - - The name of the publisher of a document - - - - -
- -
- - - - - - - - - - - - - - - - - Information about a particular release of a document - - - - -
- -
- - - - - - - - - - - - - - - - - - - - - A history of the revisions to a document - - - If this element is the root element, it must have a version attribute. - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - An entry describing a single revision in the history of the revisions to a document - - - - - - - - - - - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - A document revision number - - - - -
- -
- - - - - - - - - - - - - - - - - A description of a revision to a document - - - - -
- -
- - - - - - - - - - - - - - - - - A extended description of a revision to a document - - - - - - -
- -
- - - - - - - - - - - - - - - - - Numbers of the volumes in a series of books - - - - -
- -
- - - - - - - - - - - - - - - - - The volume number of a document in a set (as of books in a set or articles in a journal) - - - - -
- -
- - - - - - - - - - - - - - - - - The number of an issue of a journal - - - - -
- -
- - - - - - - - - - - - - - - - - A software or application package - - - - -
- -
- - - - - - - - - - - - - - - - - An email address - - - - -
- -
- - - - - - - - - - - - - - - - - A comment on a line in a verbatim listing - - - - -
- -
- - - command - A command - function - A function - option - An option - - - - - - Identifies the class of parameter - - - - - - - - - - - - - - - - - - - - - - - - A value or a symbolic reference to a value - - - - -
- - - - - - - - -
- - - command - A command - function - A function - option - An option - parameter - A parameter - - - - - - Identifies the nature of the replaceable text - - - - - - - - - - - - - - - - - - - - - - - - Content that may or must be replaced by the user - - - - - - -
- -
- - - - Identifies the type of URI specified - - - - - - - - - - - - - - - - - - - - - - A Uniform Resource Identifier - - - - -
- -
- - - - - - - - - - - - - - - - - An abbreviation, especially one followed by a period - - - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - An often pronounceable word made from the initial (or selected) letters of a name or phrase - - - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - An inline bibliographic reference to another published work - - - - - - -
- -
- - - - - - - - - - - - - - - - - A citation to a reference page - - - - - - - -
- -
- - - - - - - - - - - - - - - - - The title of a reference page - - - - - - -
- -
- - - - - - - - - - - - - - - - - A reference volume number - - - - -
- -
- - - article - An article - bbs - A bulletin board system - book - A book - cdrom - A CD-ROM - chapter - A chapter (as of a book) - dvd - A DVD - emailmessage - An email message - gopher - A gopher page - journal - A journal - manuscript - A manuscript - newsposting - A posting to a newsgroup - part - A part (as of a book) - refentry - A reference entry - section - A section (as of a book or article) - series - A series - set - A set (as of books) - webpage - A web page - wiki - A wiki page - - - - - - Identifies the nature of the publication being cited - - - - - - - - - - - - - - - - - - - - - - - - The title of a cited work - - - - - - -
- -
- - - - - - - - - - - - - - - - - Emphasized text - - - - - - -
- -
- - - A limited span of emphasized text - - - - -
- -
- - - - - - - - - - - - - - - - - A word or phrase in a language other than the primary language of the document - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - A limited word or phrase in a language other than the primary language of the document - - - - -
- -
- - - - - - - - - - - - - - - - - A span of text - - - - - - -
- -
- - - A limited span of text - - - - -
- -
- - - - - - - - - - - - - - - - - An inline quotation - - - - - - -
- -
- - - - - - - - - - - - - - - - - A limited inline quotation - - - - -
- -
- - - - - - - - - - - - - - - - - A subscript (as in H2 -O, the molecular formula for water) - - - - -
- -
- - - - - - - - - - - - - - - - - A superscript (as in x2 -, the mathematical notation for x multiplied by itself) - - - - -
- -
- - - copyright - A copyright - registered - A registered copyright - service - A service - trade - A trademark - - - - - - Identifies the class of trade mark - - - - - - - - - - - - - - - - - - - - - - - - A trademark - - - - -
- -
- - - - - - - - - - - - - - - - - A word meant specifically as a word and not representing anything else - - - - -
- -
- - - - - - - - - - - - - - - - - - - - - - - - A cross reference to a footnote (a footnote mark) - - - @linkend on footnoteref must point to a footnote. - - - - - - -
- -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - A cross reference to another part of the document - - - - -
- -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - A hypertext link - - - - - - -
- -
- - - - - - - - - - - Holds additional information that may be used by the application when resolving the link - - - - - - Specifies the URI of the document in which the link target appears - - - - - - - Specifies the location of the link target in the document - - - - - - Identifies application-specific customization of the link behavior - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - A link that addresses its target indirectly - - - - - - -
- -
- - - - - - - - - - - - - - - - A spot in the document - - - - -
- -
- - - - - - - - - - - - - - - - A text-only annotation, often used for accessibility - - - - - - - - - -
- - - - Identifies the editorial or publication status of the element on which it occurs - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - A collection of books - - - If this element is the root element, it must have a version attribute. - - - - - - - - - - - - - -
- - - - - - - - - - - - - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - A book - - - If this element is the root element, it must have a version attribute. - - - - - - - -
- -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - The dedication of a book or other component - - - If this element is the root element, it must have a version attribute. - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Acknowledgements of a book or other component - - - If this element is the root element, it must have a version attribute. - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Text at the back of a book describing facts about its production - - - If this element is the root element, it must have a version attribute. - - - - - - - - - - - - - - - - - - - - - - - - -
- - - - - - - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - An appendix in a book or article - - - If this element is the root element, it must have a version attribute. - - - - - - - - - -
- - - - - - - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - A chapter, as of a book - - - If this element is the root element, it must have a version attribute. - - - - - - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - A division in a book - - - If this element is the root element, it must have a version attribute. - - - - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Introductory matter preceding the first chapter of a book - - - If this element is the root element, it must have a version attribute. - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - An introduction to the contents of a part - - - If this element is the root element, it must have a version attribute. - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - A recursive section - - - If this element is the root element, it must have a version attribute. - - - - - - - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - A section of a document with no subdivisions - - - If this element is the root element, it must have a version attribute. - - - - - - - - - -
- - - - - - - - - - - - - - - -
- - - - - - - faq - A collection of frequently asked questions. - journalarticle - An article in a journal or other periodical. - productsheet - A description of a product. - specification - A specification. - techreport - A technical report. - whitepaper - A white paper. - - - - - - Identifies the nature of the article - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - An article - - - If this element is the root element, it must have a version attribute. - - - - - - - - - - - - - - - - - - - - - - - -
- - - - Identifies one or more annotations that apply to this element - - - -
- - - - - - - Identifies one ore more elements to which this annotation applies - - - - - - - - - - - - - - - - - - - - - - An annotation - - - annotation must not occur among the children or descendants of annotation - - - - - If this element is the root element, it must have a version attribute. - - - - - - - - - -
- - - - Identifies the XLink extended link type - - - An XLink extended type element may not occur as the direct child of an XLink extended type element. - - - extended - An XLink extended link type - - - - - - Identifies the XLink locator link type - - - An XLink locator type element must occur as the direct child of an XLink extended type element. - - - locator - An XLink locator link type - - - - - - Identifies the XLink arc link type - - - An XLink arc type element must occur as the direct child of an XLink extended type element. - - - arc - An XLink arc link type - - - - - - Identifies the XLink resource link type - - - An XLink resource type element must occur as the direct child of an XLink extended type element. - - - resource - An XLink resource link type - - - - - - Identifies the XLink title link type - - - An XLink title type element must occur as the direct child of an XLink extended, locator, or arc type element. - - - title - An XLink title link type - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Specifies the XLink traversal-from - - - - - - - Specifies the XLink label - - - - - - - Specifies the XLink traversal-to - - - - -
- - - - - - - - - - - - - Identifies the XLink link type - extended - An XLink extended link - - - - - - - - - - - - - - An XLink extended link - - - - - - - - - - -
- -
- - - - - - - - - - - - - Identifies the XLink link type - locator - An XLink locator link - - - - - - - - - - - - - - - - - - An XLink locator in an extendedlink - - - - -
- -
- - - - - - - - - - - - - Identifies the XLink link type - arc - An XLink arc link - - - - - - - - - - - - - - - - - - - - - - - - - - An XLink arc in an extendedlink - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - A top-level section of document - - - If this element is the root element, it must have a version attribute. - - - - - - - - - - - - - - - - - - - - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - A subsection within a sect1 - - - If this element is the root element, it must have a version attribute. - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - A subsection within a sect2 - - - If this element is the root element, it must have a version attribute. - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - A subsection within a sect3 - - - If this element is the root element, it must have a version attribute. - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - - - - - - - - - - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - A subsection within a sect4 - - - If this element is the root element, it must have a version attribute. - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - A collection of reference entries - - - If this element is the root element, it must have a version attribute. - - - - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - A reference page (originally a UNIX man-style reference page) - - - If this element is the root element, it must have a version attribute. - - - - - - - - - - - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - Meta-information for a reference entry - - - - - - - - - - - - - - - - -
- - - - source - The name of the software product or component to which this topic applies - version - The version of the software product or component to which this topic applies - manual - The section title of the reference page (e.g., User Commands) - sectdesc - The section title of the reference page (believed synonymous with "manual" but in wide use) - software - The name of the software product or component to which this topic applies (e.g., SunOS x.y; believed synonymous with "source" but in wide use) - - - - - - - Identifies the kind of miscellaneous information - - - - - - - - Identifies the nature of non-standard miscellaneous information - - - - - - - Identifies the kind of miscellaneious information - other - Indicates that the information is some 'other' kind. - - - - - - - - - - - - -
- - - - - - - - - - - - - - - - - - - - Meta-information for a reference entry other than the title and volume number - - - - -
- -
- - - - - - - - - - - - - - - - - The name, purpose, and classification of a reference page - - - - - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - A description of the topic of a reference page - - - - - - -
- -
- - - - - - - - - - - - - - - - - The name of (one of) the subject(s) of a reference page - - - - - - -
- -
- - - - - - - - - - - - - - - - - A short (one sentence) synopsis of the topic of a reference page - - - - - - -
- -
- - - - - - - - - - - - - - - - - The scope or other indication of applicability of a reference entry - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - - - - - A syntactic synopsis of the subject of the reference page - - - If this element is the root element, it must have a version attribute. - - - - - - - - - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - A recursive section in a refentry - - - If this element is the root element, it must have a version attribute. - - - - - - - - - - - - - - - - - - - -
- - - - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - A major subsection of a reference entry - - - If this element is the root element, it must have a version attribute. - - - - - - - - - - - - - - - - - -
- - - - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - A subsection of a refsect1 - - - If this element is the root element, it must have a version attribute. - - - - - - - - - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - A subsection of a refsect2 - - - If this element is the root element, it must have a version attribute. - - - - - - - - - -
- - - - - - - - - - - - - - Specifies the base form of the term, the one that appears in the glossary. This allows adjectival, plural, and other variations of the term to appear in the element. The element content is the default base form. - - - - -
- - - - - - - - - - - - - - - - - - - - - A wrapper for a list of glossary entries - - - If this element is the root element, it must have a version attribute. - - - - - - - - - - - - - - -
- -
- - - - - - - Specifies the string by which the element's content is to be sorted; if unspecified, the content is used - - - - - - - - - - - - - - - - - - - An entry in a glossary or glosslist - - - - - - - - - - - - - - - - - - - -
- -
- - - - - - - Specifies a list of keywords for the definition - - - - - - - - - - - - - - - - - - - A definition in a glossentry - - - - - - - - - -
- -
- - - - - - - Identifies the other term - - - - - - - - - - - - - - - - - - - - A cross-reference from one glossentry - to another - - - @otherterm on glosssee must point to a glossentry. - - - - - - - - -
- -
- - - - - - - Identifies the other term - - - - - - - - - - - - - - - - - - - - A cross-reference from one glossentry to another - - - @otherterm on glossseealso must point to a glossentry. - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - - The first occurrence of a term - - - @linkend on firstterm must point to a glossentry. - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - - The first occurrence of a term, with limited content - - - @linkend on firstterm must point to a glossentry. - - - - - - -
- -
- - - - - - - - - - - - - - - - - - A glossary term - - - @linkend on glossterm must point to a glossentry. - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - - A glossary term - - - @linkend on glossterm must point to a glossentry. - - - - - - -
- -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - A glossary - - - If this element is the root element, it must have a version attribute. - - - - - - - - - - - - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - A division in a glossary - - - If this element is the root element, it must have a version attribute. - - - - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - - - - - An inline definition of a term - - - A termdef must contain exactly one firstterm - - - - - - - - -
- - - - Identifies the relationship between the bibliographic elemnts - - - -
- - - - - - - - - - - - - - - - - A raw entry in a bibliography - - - - - - -
- -
- - - - - - - - - - - - - - - - - A cooked entry in a bibliography - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - - - - - - - - A raw container for related bibliographic information - - - - - - -
- -
- - - - - - - - - - - - - - - - - - - - - - - - A cooked container for related bibliographic information - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - Untyped bibliographic information - - - - -
- -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - A bibliography - - - If this element is the root element, it must have a version attribute. - - - - - - - - - - - - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - A section of a bibliography - - - If this element is the root element, it must have a version attribute. - - - - - - - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - - - - - A wrapper for a list of bibliography entries - - - If this element is the root element, it must have a version attribute. - - - - - - - - - - - - - - - - - -
- -
- - - - - - - - - - - - - - - The units (for example, pages) used to identify the beginning and ending of a reference. - - - - - - - Identifies the beginning of a reference; the location within the work that is being referenced. - - - - - - - Identifies the end of a reference. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - A cross-reference to a bibliographic entry - - - - -
- - - - normal - Normal - preferred - Preferred - - - - - - Specifies the significance of the term - - - - - - - Specifies the IDs of the elements to which this term applies - - - - - - - Indicates the page on which this index term occurs in some version of the printed document - - - - - - all - All indexes - global - The global index (as for a combined index of a set of books) - local - The local index (the index for this document only) - - - - - - Specifies the scope of the index term - - - - - - - Specifies the string by which the term is to be sorted; if unspecified, the term content is used - - - - - - Specifies the target index for this term - - - -
- - - - - - - - - - - - - - - - - A set of index terms in the meta-information of a document - - - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - - - - - Identifies the class of index term - singular - A singular index term - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - A wrapper for an indexed term - - - - -
- -
- - - - - - - Identifies the class of index term - startofrange - The start of a range - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - A wrapper for an indexed term that covers a range - - - - -
- -
- - - - - - - Identifies the class of index term - endofrange - The end of a range - - - - - - Points to the start of the range - - - - - - - - - - - - - - - - - - - Identifies the end of a range associated with an indexed term - - - - -
- -
- - - - - - - -
- -
- - - - - - - - - - - - - - - - - - - - The primary word or phrase under which an index term should be sorted - - - - - - -
- -
- - - - - - - - - - - - - - - - - - - - A secondary word or phrase in an index term - - - - - - -
- -
- - - - - - - - - - - - - - - - - - - - A tertiary word or phrase in an index term - - - - - - -
- -
- - - - - - - - normal - under - - - - - - - - - - - - - - - - - - - - Part of an index term directing the reader instead to another entry in the index - - - - - - -
- -
- - - - - - - - normal - under - - - - - - - - - - - - - - - - - - - - Part of an index term directing the reader also to another entry in the index - - - - - - -
- -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - An index to a book or part of a book - - - If this element is the root element, it must have a version attribute. - - - - - - - - - - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - An index to a set of books - - - If this element is the root element, it must have a version attribute. - - - - - - - - - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - A division in an index - - - If this element is the root element, it must have a version attribute. - - - - - - - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - An entry in an index - - - - - - - - - - - - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - - - A primary term in an index entry, not in the text - - - - - - -
- -
- - - - - - - - - - - - - - - - - - - A secondary term in an index entry, rather than in the text - - - - - - -
- -
- - - - - - - - - - - - - - - - - - - A tertiary term in an index entry, rather than in the text - - - - - - -
- -
- - - - - - - - - - - - - - - - - - - A See -entry in an index, rather than in the text - - - - - - -
- -
- - - - - - - - - - - - - - - - - - - A See also - entry in an index, rather than in the text - - - - - - -
- - - - Indicates the page on which this element occurs in some version of the printed document - - - -
- - - - - - - - - - - - - - - - - - - - - A table of contents - - - If this element is the root element, it must have a version attribute. - - - - - - - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - A division in a table of contents - - - If this element is the root element, it must have a version attribute. - - - - - - - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - - - - - - - - - - A component title in a table of contents - - - - - - -
- - - - - -
- - - - - - - - - - - - - - - - - A task to be completed - - - If this element is the root element, it must have a version attribute. - - - - - - - - - - - - - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - - - - - A summary of a task - - - If this element is the root element, it must have a version attribute. - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - - - - - The prerequisites for a task - - - If this element is the root element, it must have a version attribute. - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - - - - - Information related to a task - - - If this element is the root element, it must have a version attribute. - - - - - - - - - -
- - - - calspair - Coordinates expressed as a pair of CALS graphic coordinates. - linecolumn - Coordinates expressed as a line and column. - linecolumnpair - Coordinates expressed as a pair of lines and columns. - linerange - Coordinates expressed as a line range. - - - - - - - Identifies the units used in the coords attribute. The default units vary according to the type of callout specified: calspair - for graphics and linecolumn - for line-oriented elements. - - - - - - - - - Indicates that non-standard units are used for this area -. In this case otherunits - must be specified. - other - Coordinates expressed in some non-standard units. - - - - Identifies the units used in the coords - attribute when the units - attribute is other -. This attribute is forbidden otherwise. - - - - - - - - - - - -
- - - - - - - - - - - - - - - - - - - - - A list of callout -s - - - If this element is the root element, it must have a version attribute. - - - - - - - - - - - - -
- -
- - - - - - - Identifies the areas described by this callout. - - - - - - - - - - - - - - - - - A called out - description of a marked area - - - - - - -
- -
- - - - - - - - - - - - - - - - - - - - - A program listing with associated areas used in callouts - - - If this element is the root element, it must have a version attribute. - - - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - - A collection of regions in a graphic or code example - - - - - - - - - -
- -
- - - - - - - Point to the callout -s which refer to this area. (This provides bidirectional linking which may be useful in online presentation.) - - - - - - - Specifies an identifying number or string that may be used in presentation. The area label might be drawn on top of the figure, for example, at the position indicated by the coords attribute. - - - - - - Provides the coordinates of the area. The coordinates must be interpreted using the units - specified. - - - - - - - - - - - - - - - - - - - - - - - - - - A region defined for a callout in a graphic or code example - - - - - - -
- -
- - - - - - - - - - - - - - - - - - - - - - A region defined for a callout in a graphic or code example - - - - - - -
- -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - A set of related areas in a graphic or code example - - - - - - -
- -
- - - - - - - - - - - - - - - - - - - - - A screen with associated areas used in callouts - - - If this element is the root element, it must have a version attribute. - - - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - - - - - A wrapper for an image object with callouts - - - If this element is the root element, it must have a version attribute. - - - - - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - The location of a callout embedded in text - - - - -
- -
- - - - - - - - - - - - - - - - - - - - - - - - A cross reference to a co - - - - -
- -
- - - - - - - - - - - - - - - - - - - - - A set of EBNF productions - - - If this element is the root element, it must have a version attribute. - - - - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - A production in a set of EBNF productions - - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - The left-hand side of an EBNF production - - - - -
- -
- - - - - - - - - - - - - - - - - The right-hand side of an EBNF production - - - - - - - - - - - -
- -
- - - - - - - Specifies a URI that points to a production -where the nonterminal - is defined - - - - - - - - - - - - - - - - - - A non-terminal in an EBNF production - - - - -
- -
- - - - - - - - - - - - - - - - - A constraint in an EBNF production - - - - -
- -
- - - - - - - - - - - - - - - - - A cross-reference to an EBNF production - - - - -
- -
- - - - - - - - - - - - - - - - - - - - - The definition of a constraint in an EBNF production - - - If this element is the root element, it must have a version attribute. - - - - - - - - - -
- - - - Specifies the alignment character when align - is set to char -. - - - - - - Specifies the percentage of the column's total width that should appear to the left of the first occurance of the character identified in char - when align - is set to char -. - - 0 - 100 - - - - - - - Specifies how the table is to be framed. Note that there is no way to obtain a border on only the starting edge (left, in left-to-right writing systems) of the table. - - all - Frame all four sides of the table. In some environments with limited control over table border formatting, such as HTML, this may imply additional borders. - bottom - Frame only the bottom of the table. - none - Place no border on the table. In some environments with limited control over table border formatting, such as HTML, this may disable other borders as well. - sides - Frame the left and right sides of the table. - top - Frame the top of the table. - topbot - Frame the top and bottom of the table. - - - - - - - Specifies the presence or absence of the column separator - - 0 - No column separator rule. - 1 - Provide a column separator rule on the right - - - - - - - Specifies the presence or absence of the row separator - - 0 - No row separator rule. - 1 - Provide a row separator rule below - - - - - - - Specifies the orientation of the table - - land - 90 degrees counter-clockwise from the rest of the text flow. - port - The same orientation as the rest of the text flow. - - - - - - - Specifies the table style - - - - - - Indicates whether or not the entries in the first column should be considered row headers - - firstcol - Indicates that entries in the first column of the table are functionally row headers (analogous to the way that a thead provides column headers). - headers - Indicates that row headers are identified by use of the headers attribute on entries in the table. - norowheader - Indicates that entries in the first column have no special significance with respect to column headers. - - - - - - - Specifies the horizontal alignment of text in an entry. - - center - Centered. - char - Aligned on a particular character. - justify - Left and right justified. - left - Left justified. - right - Right justified. - - - - - - - Specifies the vertical alignment of text in an entry. - - bottom - Aligned on the bottom of the entry. - middle - Aligned in the middle. - top - Aligned at the top of the entry. - - - - - - - Specifies a column specification by name. - - - - - - Specifies a starting column by name. - - - - - - Specifies a span by name. - - - - - - - Specifies a starting column by name. - - - Specifies an ending column by name. - - - - - - - - - - - - - - - - Provides a name for a column specification. - - - - - - Provides a name for a span specification. - - - -
- - - - - - - Additional style information for downstream processing; typically the name of a style. - - - - - - The number of columns in the table. Must be an integer greater than zero. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - A wrapper for the main content of a table, or part of a table - - - - - - - - - - - - - - - - -
- -
- - - - - - - The number of the column to which this specification applies. Must be greater than any preceding column number. Defaults to one more than the number of the preceding column, if there is one, or one. - - - - - - - Specifies the width of the column. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Specifications for a column in a table - - - - -
- -
- - - - - - - Specifies a starting column by name. - - - - - - Specifies an ending column by name. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Formatting information for a spanned column in a table - - - - -
- -
- - - - - - - - - - - - - - - - - - - - A table header consisting of one or more rows - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - - - - A table footer consisting of one or more rows - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - - - - A wrapper for the rows of a table or informal table - - - - - - -
- -
- - - - - - - - - - - - - - - - - - - - - - - A row in a table - - - - - - - - - -
- -
- - - - - - - Specifies the number of additional rows which this entry occupies. Defaults to zero. - - - - - - - Specifies the rotation of this entry. A value of 1 (true) rotates the cell 90 degrees counter-clockwise. A value of 0 (false) leaves the cell unrotated. - - 0 - Do not rotate the cell. - 1 - Rotate the cell 90 degrees counter-clockwise. - - - - - - - Specifies the scope of a header. - - row - Applies to the row - col - Applies to the column - rowgroup - Applies to the row group - colgroup - Applies to the column group - - - - - - - Specifies the entry or entries which serve as headers for this element. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - A cell in a table - - - table must not occur among the children or descendants of entry - - - - - informaltable must not occur among the children or descendants of entry - - - - - - - - - - - - - -
- -
- - - - - - - Additional style information for downstream processing; typically the name of a style. - - - - - - The number of columns in the entry table. Must be an integer greater than zero. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - A subtable appearing in place of an entry in a table - - - - - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - - - - A table header consisting of one or more rows - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - - - - A wrapper for the rows of a table or informal table - - - - - - -
- -
- - - - - - - - - - - - - - - - - - - - - - - A row in a table - - - - - - -
- -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Indicates if the short or long title should be used in a List of Tables - - 0 - Indicates that the full title should be used. - 1 - Indicates that the short short title (titleabbrev) should be used. - - - - - - Indicates if the table should appear in a List of Tables - - 0 - Indicates that the table should not occur in the List of Tables. - 1 - Indicates that the table should appear in the List of Tables. - - - - - - - - - - - - - - - - A formal table in a document - - - example must not occur among the children or descendants of table - - - - - figure must not occur among the children or descendants of table - - - - - equation must not occur among the children or descendants of table - - - - - If this element is the root element, it must have a version attribute. - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - A table without a title - - - If this element is the root element, it must have a version attribute. - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - - - - This attribute assigns a class name or set of class names to an element. Any number of elements may be assigned the same class name or names. Multiple class names must be separated by white space characters. - - - - - This attribute specifies style information for the current element. - - - - - This attribute offers advisory information about the element for which it is set. - - - - - - - - - This attribute specifies the base language of an element's attribute values and text content. The default value of this attribute is unknown. - - - - - - - - - Occurs when the pointing device button is clicked over an element. - - - - - Occurs when the pointing device button is double clicked over an element. - - - - - Occurs when the pointing device button is pressed over an element. - - - - - Occurs when the pointing device button is released over an element. - - - - - Occurs when the pointing device is moved onto an element. - - - - - Occurs when the pointing device is moved while it is over an element. - - - - - Occurs when the pointing device is moved away from an element. - - - - - Occurs when a key is pressed and released over an element. - - - - - Occurs when a key is pressed down over an element. - - - - - Occurs when a key is released over an element. - - - - - - - - - - - - - - - - - - - Specifies the alignment of data and the justification of text in a cell. - - left - Left-flush data/Left-justify text. This is the default value for table data. - center - Center data/Center-justify text. This is the default value for table headers. - right - Right-flush data/Right-justify text. - justify - Double-justify text. - char - Align text around a specific character. If a user agent doesn't support character alignment, behavior in the presence of this value is unspecified. - - - - - - This attribute specifies a single character within a text fragment to act as an axis for alignment. The default value for this attribute is the decimal point character for the current language as set by the lang attribute (e.g., the period in English and the comma in French). User agents are not required to support this attribute. - - - - - When present, this attribute specifies the offset to the first occurrence of the alignment character on each line. If a line doesn't include the alignment character, it should be horizontally shifted to end at the alignment position. When charoff is used to set the offset of an alignment character, the direction of offset is determined by the current text direction (set by the dir attribute). In left-to-right texts (the default), offset is from the left margin. In right-to-left texts, offset is from the right margin. User agents are not required to support this attribute. - - - An explicit offset. - - [0-9]+% - - A percentage offset. - - - - - - - - - - Specifies the vertical position of data within a cell. - - top - Cell data is flush with the top of the cell. - middle - Cell data is centered vertically within the cell. This is the default value. - bottom - Cell data is flush with the bottom of the cell. - baseline - All cells in the same row as a cell whose valign attribute has this value should have their textual data positioned so that the first text line occurs on a baseline common to all cells in the row. This constraint does not apply to subsequent text lines in these cells. - - - - - - - - - - Provides a summary of the table's purpose and structure for user agents rendering to non-visual media such as speech and Braille. - - - - - Specifies the desired width of the entire table and is intended for visual user agents. When the value is a percentage value, the value is relative to the user agent's available horizontal space. In the absence of any width specification, table width is determined by the user agent. - - - An explicit width. - - [0-9]+% - - A percentage width. - - - - - - Specifies the width (in pixels only) of the frame around a table. - - - - - - Specifies which sides of the frame surrounding a table will be visible. - - void - No sides. This is the default value. - above - The top side only. - below - The bottom side only. - hsides - The top and bottom sides only. - lhs - The left-hand side only. - rhs - The right-hand side only. - vsides - The right and left sides only. - box - All four sides. - border - All four sides. - - - - - - Specifies which rules will appear between cells within a table. The rendering of rules is user agent dependent. - - none - No rules. This is the default value. - groups - Rules will appear between row groups (see thead, tfoot, and tbody) and column groups (see colgroup and col) only. - rows - Rules will appear between rows only. - cols - Rules will appear between columns only. - all - Rules will appear between all rows and columns. - - - - - - Specifies how much space the user agent should leave between the left side of the table and the left-hand side of the leftmost column, the top of the table and the top side of the topmost row, and so on for the right and bottom of the table. The attribute also specifies the amount of space to leave between cells. - - - An explicit spacing. - - [0-9]+% - - A percentage spacing. - - - - - - Specifies the amount of space between the border of the cell and its contents. If the value of this attribute is a pixel length, all four margins should be this distance from the contents. If the value of the attribute is a percentage length, the top and bottom margins should be equally separated from the content based on a percentage of the available vertical space, and the left and right margins should be equally separated from the content based on a percentage of the available horizontal space. - - - An explicit padding. - - [0-9]+% - - A percentage padding. - - - - - - - - - - - Provides an abbreviated form of the cell's content and may be rendered by user agents when appropriate in place of the cell's content. Abbreviated names should be short since user agents may render them repeatedly. For instance, speech synthesizers may render the abbreviated headers relating to a particular cell before rendering that cell's content. - - - - - This attribute may be used to place a cell into conceptual categories that can be considered to form axes in an n-dimensional space. User agents may give users access to these categories (e.g., the user may query the user agent for all cells that belong to certain categories, the user agent may present a table in the form of a table of contents, etc.). Please consult an HTML reference for more details. - - - - - Specifies the list of header cells that provide header information for the current data cell. The value of this attribute is a space-separated list of cell names; those cells must be named by setting their id attribute. Authors generally use the headers attribute to help non-visual user agents render header information about data cells (e.g., header information is spoken prior to the cell data), but the attribute may also be used in conjunction with style sheets. - - - - - Specifies the set of data cells for which the current header cell provides header information. This attribute may be used in place of the headers attribute, particularly for simple tables. - - row - The current cell provides header information for the rest of the row that contains it - col - The current cell provides header information for the rest of the column that contains it. - rowgroup - The header cell provides header information for the rest of the row group that contains it. - colgroup - The header cell provides header information for the rest of the column group that contains it. - - - - - - Specifies the number of rows spanned by the current cell. The default value of this attribute is one (1 -). The value zero (0 -) means that the cell spans all rows from the current row to the last row of the table section (thead -, tbody -, or tfoot -) in which the cell is defined. - - - - - - Specifies the number of columns spanned by the current cell. The default value of this attribute is one (1 -). The value zero (0 -) means that the cell spans all columns from the current column to the last column of the column group (colgroup -) in which the cell is defined. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - A formal (captioned) HTML table in a document - - - example must not occur among the children or descendants of table - - - - - figure must not occur among the children or descendants of table - - - - - equation must not occur among the children or descendants of table - - - - - If this element is the root element, it must have a version attribute. - - - - - - -
- -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - An HTML table without a title - - - If this element is the root element, it must have a version attribute. - - - - - - -
- -
- - - - - - - An HTML table caption - - - example must not occur among the children or descendants of caption - - - - - figure must not occur among the children or descendants of caption - - - - - table must not occur among the children or descendants of caption - - - - - equation must not occur among the children or descendants of caption - - - - - sidebar must not occur among the children or descendants of caption - - - - - task must not occur among the children or descendants of caption - - - - - caution must not occur among the children or descendants of caption - - - - - important must not occur among the children or descendants of caption - - - - - note must not occur among the children or descendants of caption - - - - - tip must not occur among the children or descendants of caption - - - - - warning must not occur among the children or descendants of caption - - - - - If this element is the root element, it must have a version attribute. - - - - - - - - -
- -
- - - - - - This attribute, whose value must be an integer > 0, specifies the number of columns spanned - by the col - element; the col - element shares its attributes with all the columns it spans. The default value for this attribute is 1 (i.e., a single column). If the span attribute is set to N > 1, the current col - element shares its attributes with the next N-1 columns. - - - - - - Specifies a default width for each column spanned by the current col - element. It has the same meaning as the width - attribute for the colgroup - element and overrides it. - - - - - - - - - - Specifications for a column in an HTML table - - - - -
- -
- - - - - - This attribute, which must be an integer > 0, specifies the number of columns in a column group. In the absence of a span attribute, each colgroup - defines a column group containing one column. If the span attribute is set to N > 0, the current colgroup - element defines a column group containing N columns. User agents must ignore this attribute if the colgroup - element contains one or more col - elements. - - - - - - This attribute specifies a default width for each column in the current column group. In addition to the standard pixel, percentage, and relative values, this attribute allows the special form 0* - (zero asterisk) which means that the width of the each column in the group should be the minimum width necessary to hold the column's contents. This implies that a column's entire contents must be known before its width may be correctly computed. Authors should be aware that specifying 0* - will prevent visual user agents from rendering a table incrementally. This attribute is overridden for any column in the column group whose width is specified via a col - element. - - - - - - - - - - A group of columns in an HTML table - - - - - - -
- -
- - - - - - - - - - - A table header consisting of one or more rows in an HTML table - - - - - - -
- -
- - - - - - - - - - - A table footer consisting of one or more rows in an HTML table - - - - - - -
- -
- - - - - - - - - - - A wrapper for the rows of an HTML table or informal HTML table - - - - - - -
- -
- - - - - - - - - - - A row in an HTML table - - - - - - - - - -
- -
- - - - - - - - - - - - A table header entry in an HTML table - - - - - - - - - - - -
- -
- - - - - - - - - - - - A table entry in an HTML table - - - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - - - - - A detailed set of messages, usually error messages - - - If this element is the root element, it must have a version attribute. - - - - - - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - A wrapper for an entry in a message set - - - - - - - - - - - - -
- -
- - - - - - - The audience to which the message relevant - - - - - - The origin of the message - - - - - - The level of importance or severity of a message - - - - - - - - - - - - - - - - - - - - - - - - - A wrapper for a simpler entry in a message set - - - - - - - -
- -
- - - - - - - - - - - - - - - - - - - - - A message in a message set - - - If this element is the root element, it must have a version attribute. - - - - - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - - - - - The primary component of a message in a message set - - - If this element is the root element, it must have a version attribute. - - - - - - - -
- -
- - - - - - - - - - - - - - - - - - - - - A subcomponent of a message in a message set - - - If this element is the root element, it must have a version attribute. - - - - - - - -
- -
- - - - - - - - - - - - - - - - - - - - - A related component of a message in a message set - - - If this element is the root element, it must have a version attribute. - - - - - - - -
- -
- - - - - - - - - - - - - - - - - The actual text of a message component in a message set - - - - - - -
- -
- - - - - - - - - - - - - - - - - Information about a message in a message set - - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - The level of importance or severity of a message in a message set - - - - -
- -
- - - - - - - - - - - - - - - - - The origin of a message in a message set - - - - -
- -
- - - - - - - - - - - - - - - - - The audience to which a message in a message set is relevant - - - - -
- -
- - - - - - - - - - - - - - - - - - - - - Explanatory material relating to a message in a message set - - - If this element is the root element, it must have a version attribute. - - - - - - - - - -
- -
- - - - - - - none - No labels - number - Numeric labels - qanda - "Q:" and "A:" labels - - - - - - Specifies the default labelling - - - - - - - - - - - - - - - - - - - - - - - - A question-and-answer set - - - If this element is the root element, it must have a version attribute. - - - - - - - - - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - - - - - A titled division in a qandaset - - - If this element is the root element, it must have a version attribute. - - - - - - - - - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - - - - - A question/answer set within a qandaset - - - If this element is the root element, it must have a version attribute. - - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - A question in a qandaset - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - An answer to a question posed in a qandaset - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - A label on a question or answer - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - A displayed mathematical equation - - - example must not occur among the children or descendants of equation - - - - - figure must not occur among the children or descendants of equation - - - - - table must not occur among the children or descendants of equation - - - - - equation must not occur among the children or descendants of equation - - - - - If this element is the root element, it must have a version attribute. - - - - - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - - - - - - - - - - - A displayed mathematical equation without a title - - - If this element is the root element, it must have a version attribute. - - - - - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - A mathematical equation or expression occurring inline - - - - - - - -
- -
- - - - - - - - - - - - - - - - - A mathematical phrase that can be represented with ordinary text and a small amount of markup - - - - - - - - - - -
- - - - - - - - -
- - - - - - - - - - - - - Specifies that the format of the data is MathML - mathml - Specifies MathML. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - A MathML expression in a media object - - - If this element is the root element, it must have a version attribute. - - - - - - - - - -
- -
- - - Any element from the MathML namespace - - - - - - - - - - -
- - - - - - - - -
- - - - - - - - - - - - - Specifies that the format of the data is SVG - svg - Specifies SVG. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - An SVG drawing in a media object - - - If this element is the root element, it must have a version attribute. - - - - - - - - - -
- -
- - - Any element from the SVG namespace - - - - - - - - - - -
- - - - - - - - - - - - - - - -
- - - - - - - - - - - - - - - - - A string of formatting markup in text that is to be represented literally - - - - -
- -
- - - - - - - attribute - An attribute - attvalue - An attribute value - element - An element - emptytag - An empty element tag - endtag - An end tag - genentity - A general entity - localname - The local name part of a qualified name - namespace - A namespace - numcharref - A numeric character reference - paramentity - A parameter entity - pi - A processing instruction - prefix - The prefix part of a qualified name - comment - An SGML comment - starttag - A start tag - xmlpi - An XML processing instruction - - - - - - Identifies the nature of the tag content - - - - - - - Identifies the namespace of the tag content - - - - - - - - - - - - - - - - - - - - - - - A component of XML (or SGML) markup - - - - - - - - - -
- -
- - - Identifies the class of symbol - limit - The value is a limit of some kind - - - - - - - - - - - - - - - - - - - - - - - A name that is replaced by a value before processing - - - - -
- -
- - - - - - - - - - - - - - - - - A unit of information - - - - -
- -
- - - - - - - - - - - - - - - - - Inline text that is some literal value - - - - -
- -
- - - Identifies the (computer) language of the code fragment - - - - - - - - - - - - - - - - - - - - - - - An inline code fragment - - - - - - - - - -
- -
- - - Identifies the class of constant - limit - The value is a limit of some kind - - - - - - - - - - - - - - - - - - - - - - - A programming or system constant - - - - -
- -
- - - - - - - copyright - A name with a copyright - registered - A name with a registered copyright - service - A name of a service - trade - A name which is trademarked - - - - - - Specifies the class of product name - - - - - - - - - - - - - - - - - - - - The formal name of a product - - - - -
- -
- - - - - - - - - - - - - - - - - A number assigned to a product - - - - -
- -
- - - altkey - An alternate or secondary key - constraint - A constraint - datatype - A data type - field - A field - foreignkey - A foreign key - group - A group - index - An index - key1 - The first or primary key - key2 - An alternate or secondary key - name - A name - primarykey - The primary key - procedure - A (stored) procedure - record - A record - rule - A rule - secondarykey - The secondary key - table - A table - user - A user - view - A view - - - - - - Identifies the class of database artifact - - - - - - - - - - - - - - - - - - - - - - - - The name of a database, or part of a database - - - - -
- -
- - - hardware - A hardware application - software - A software application - - - - - - Identifies the class of application - - - - - - - - - - - - - - - - - - - - - - - - The name of a software program - - - - -
- -
- - - - - - - - - - - - - - - - - A physical part of a computer system - - - - -
- - - - - - - - - - - - - - -
- - - - - - - - - - - - - - - - - The text on a button in a GUI - - - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - Graphic and/or text appearing as a icon in a GUI - - - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - The text of a label in a GUI - - - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - The name of a menu in a GUI - - - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - The name of a terminal menu item in a GUI - - - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - The name of a submenu in a GUI - - - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - A selection or series of selections from a menu - - - - - - - - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - The conventional name of a mouse button - - - - -
- - - - - - - - - - - - -
- - - alt - The "Alt" key - altgr - The "Alt Graph" key - backspace - The "Backspace" key - command - The "Command" key - control - The "Control" key - delete - The "Delete" key - down - The down arrow - end - The "End" key - enter - The "Enter" key - escape - The "Escape" key - home - The "Home" key - insert - The "Insert" key - left - The left arrow - meta - The "Meta" key - option - The "Option" key - pagedown - The page down key - pageup - The page up key - right - The right arrow - return - The "Return" key - shift - The "Shift" key - space - The spacebar - tab - The "Tab" key - up - The up arrow - - - - - - - Identifies the function key - - - - - - - - - Identifies the function key - other - Indicates a non-standard function key - - - - Specifies a keyword that identifies the non-standard key - - - - - - - - - - - - - - - - - - - - - - - - - - - - The text printed on a key on a keyboard - - - - -
- -
- - - - - - - - - - - - - - - - - The internal, frequently numeric, identifier for a key on a keyboard - - - - -
- - - - - - - - - - - - -
- - - click - A (single) mouse click. - double-click - A double mouse click. - press - A mouse or key press. - seq - Sequential clicks or presses. - simul - Simultaneous clicks or presses. - - - - - - - Identifies the nature of the action taken. If keycombo - contains more than one element, simul - is the default, otherwise there is no default. - - - - - - - - - Identifies the nature of the action taken - other - Indicates a non-standard action - - - - Identifies the non-standard action in some unspecified way. - - - - - - - - - - - - - - - - - - - - - - - - - - - - A combination of input actions - - - - - - -
- -
- - - - - - - - - - - - - - - - - The symbolic name of a key on a keyboard - - - - -
- -
- - - - - - - - - - - - - - - - - A graphical user interface (GUI) keyboard shortcut - - - - -
- -
- - - - - - - - - - - - - - - - - - - - - - A key combination for an action that is also accessible through a menu - - - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - - - - - - - - - - - - - - - A character or string indicating the start of an input field in a computer display - - - - - - -
- -
- - - - - - - - - - - - - - - - - A software environment variable - - - - -
- -
- - - devicefile - A device - directory - A directory - extension - A filename extension - headerfile - A header file (as for a programming language) - libraryfile - A library file - partition - A partition (as of a hard disk) - symlink - A symbolic link - - - - - - Identifies the class of filename - - - - - - - Specifies the path of the filename - - - - - - - - - - - - - - - - - - - - - - - - - - The name of a file - - - - -
- -
- - - - - - - - - - - - - - - - - The name of an executable program or other software command - - - - -
- -
- - - - - - - - - - - - - - - - - Data, generally text, displayed or presented by a computer - - - - - - -
- -
- - - - - - - - - - - - - - - - - Data entered by the user - - - - - - -
- -
- - - - - - - Specifies the character that should separate the command and its top-level arguments - - - - - - Indicates the displayed length of the command; this information may be used to intelligently indent command synopses which extend beyond one line - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - A syntax summary for a software command - - - If this element is the root element, it must have a version attribute. - - - - - - - - - - - - - - - - - -
- - - - norepeat - Can not be repeated. - repeat - Can be repeated. - - - - - - Indicates whether or not repetition is possible. - - - - - - - opt - Formatted to indicate that it is optional. - plain - Formatted without indication. - req - Formatted to indicate that it is required. - - - - - - Indicates optionality. - - - - - - - Indicates optionality. - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - An argument in a cmdsynopsis - - - - - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - A group of elements in a cmdsynopsis - - - - - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - An explicit line break in a command synopsis - - - - -
- -
- - - - - - - - - - - - - - - - - A portion of a cmdsynopsis broken out from the main body of the synopsis - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - A reference to a fragment of a command synopsis - - - @linkend on synopfragmentref must point to a synopfragment. - - - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - - A general-purpose element for representing the syntax of commands or functions - - - If this element is the root element, it must have a version attribute. - - - - - - -
- -
- - - - - - - - - - - - - - - - - - - - - - - - The syntax summary for a function definition - - - If this element is the root element, it must have a version attribute. - - - - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - - Information supplementing the funcdefs of a funcsynopsis - - - If this element is the root element, it must have a version attribute. - - - - - - -
- -
- - - - - - - - - - - - - - - - - The prototype of a function - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - A function (subroutine) name and its return type - - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - The name of a function or subroutine, as in a programming language - - - - -
- -
- - - - - - - - - - - - - - - - - An empty element in a function synopsis indicating that the function in question takes no arguments - - - - -
- -
- - - - - - - - - - - - - - - - - An empty element in a function synopsis indicating a variable number of arguments - - - - -
- -
- - - - - - - - - - - - - - - - - - - - - - - - A group of parameters - - - - - - - - - -
- -
- - - - - - - opt - Formatted to indicate that it is optional. - req - Formatted to indicate that it is required. - - - - - - Indicates optionality. - - - - - - - - - - - - - - - - - - - - Information about a function parameter in a programming language - - - - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - Parameters for a function referenced through a function pointer in a synopsis - - - - -
- -
- - - - - - - class - This is the synopsis of a class - interface - This is the synopsis of an interface - - - - - - Specifies the nature of the synopsis - - - - - - - - - - - - - - - - - - - - - - - The syntax summary for a class definition - - - If this element is the root element, it must have a version attribute. - - - - - - - - - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - - Information supplementing the contents of a classsynopsis - - - If this element is the root element, it must have a version attribute. - - - - - - -
- -
- - - - - - - - - - - - - - - - - A class in an object-oriented programming language - - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - An interface in an object-oriented programming language - - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - An exception in an object-oriented programming language - - - - - - - - - - -
- - - - Can be used to indicate that whitespace in the modifier should be preserved (for multi-line annotations, for example). - preserve - Extra whitespace and line breaks must be preserved. - - - -
- - - - - - - - - - - - - - - - - - - - Modifiers in a synopsis - - - - -
- -
- - - - - - - - - - - - - - - - - The name of an interface - - - - -
- -
- - - - - - - - - - - - - - - - - The name of an exception - - - - -
- -
- - - - - - - - - - - - - - - - - - - - The name of a field in a class definition - - - If this element is the root element, it must have a version attribute. - - - - - - - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - - - - - - - - - The initializer for a fieldsynopsis - - - - - - -
- -
- - - - - - - - - - - - - - - - - - - - A syntax summary for a constructor - - - If this element is the root element, it must have a version attribute. - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - - - - A syntax summary for a destructor - - - If this element is the root element, it must have a version attribute. - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - - - - A syntax summary for a method - - - If this element is the root element, it must have a version attribute. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - The name of a method - - - - -
- -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Parameters to a method - - - - - - - - - - - - - - - - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - - - - - - - - A group of method parameters - - - - - - - - - -
- -
- - - - - - - - - - - - - - - - - The name of a variable - - - - -
- -
- - - - - - - - - - - - - - - - - The value returned by a function - - - - -
- -
- - - - - - - - - - - - - - - - - The classification of a value - - - - -
- -
- - - - - - - - - - - - - - - - - The name of a class, in the object-oriented programming sense - - - - -
- -
- - - - - - - - - - - - - - - - - - - - - - - - - A literal listing of all or part of a program - - - If this element is the root element, it must have a version attribute. - - - - - - -
- - - - - - - - - - - - - - - - - - -
- - - - - - - - - - - - - - - - - A note of caution - - - caution must not occur among the children or descendants of caution - - - - - important must not occur among the children or descendants of caution - - - - - note must not occur among the children or descendants of caution - - - - - tip must not occur among the children or descendants of caution - - - - - warning must not occur among the children or descendants of caution - - - - - If this element is the root element, it must have a version attribute. - - - - - - -
- -
- - - - - - - - - - - - - - - - - An admonition set off from the text - - - caution must not occur among the children or descendants of important - - - - - important must not occur among the children or descendants of important - - - - - note must not occur among the children or descendants of important - - - - - tip must not occur among the children or descendants of important - - - - - warning must not occur among the children or descendants of important - - - - - If this element is the root element, it must have a version attribute. - - - - - - -
- -
- - - - - - - - - - - - - - - - - A message set off from the text - - - caution must not occur among the children or descendants of note - - - - - important must not occur among the children or descendants of note - - - - - note must not occur among the children or descendants of note - - - - - tip must not occur among the children or descendants of note - - - - - warning must not occur among the children or descendants of note - - - - - If this element is the root element, it must have a version attribute. - - - - - - -
- -
- - - - - - - - - - - - - - - - - A suggestion to the user, set off from the text - - - caution must not occur among the children or descendants of tip - - - - - important must not occur among the children or descendants of tip - - - - - note must not occur among the children or descendants of tip - - - - - tip must not occur among the children or descendants of tip - - - - - warning must not occur among the children or descendants of tip - - - - - If this element is the root element, it must have a version attribute. - - - - - - -
- -
- - - - - - - - - - - - - - - - - An admonition set off from the text - - - caution must not occur among the children or descendants of warning - - - - - important must not occur among the children or descendants of warning - - - - - note must not occur among the children or descendants of warning - - - - - tip must not occur among the children or descendants of warning - - - - - warning must not occur among the children or descendants of warning - - - - - If this element is the root element, it must have a version attribute. - - - - - - -
- - - - - - - - - - -
- - - - - - - - - - - - - - - - - An error code - - - - -
- -
- - - - - - - - - - - - - - - - - An error name - - - - -
- -
- - - - - - - - - - - - - - - - - An error message. - - - - -
- -
- - - - - - - - - - - - - - - - - The classification of an error message - - - - -
- - - - - - - - -
- - - daemon - A daemon or other system process (syslogd) - domainname - A domain name (example.com) - etheraddress - An ethernet address (00:05:4E:49:FD:8E) - event - An event of some sort (SIGHUP) - eventhandler - An event handler of some sort (hangup) - filesystem - A filesystem (ext3) - fqdomainname - A fully qualified domain name (my.example.com) - groupname - A group name (wheel) - ipaddress - An IP address (127.0.0.1) - library - A library (libncurses) - macro - A macro - netmask - A netmask (255.255.255.192) - newsgroup - A newsgroup (comp.text.xml) - osname - An operating system name (Hurd) - process - A process (gnome-cups-icon) - protocol - A protocol (ftp) - resource - A resource - securitycontext - A security context (a role, permission, or security token, for example) - server - A server (mail.example.com) - service - A service (ppp) - systemname - A system name (hephaistos) - username - A user name (ndw) - - - - - - - Identifies the nature of the system item - - - - - - - - Identifies the nature of the non-standard system item - - - - - - - - Identifies the kind of systemitemgraphic identifier - other - Indicates that the system item is some 'other' kind. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - A system-related item or term - - - - - - -
- -
- - - - - - - - - - - - - - - - - An option for a software command - - - - -
- -
- - - - - - - - - - - - - - - - - Optional information - - - - -
- -
- - - - - - - - - - - - - - - - - A unit of data associated with some part of a computer system - - - - -
- -
- - - - - - - - - - - Identifies the topic type - - - - - - - - - - - - - - - - - - - - - - - - - - - - - A modular unit of documentation not part of any particular narrative flow - - - If this element is the root element, it must have a version attribute. - - - - - - - - - - - - - -
- -
- - - - - - - - - - - - - - - [^#]+ - - - - - - - xml - text - - - - - - - - - - - - - - - - - - - - - - - An XInclude - - - - - - -
- -
- - An XInclude fallback - - - - - - - - - - - - - -
- - diff --git a/os_doc_tools/resources/extensions.rng b/os_doc_tools/resources/extensions.rng deleted file mode 100644 index 5b9a0345..00000000 --- a/os_doc_tools/resources/extensions.rng +++ /dev/null @@ -1,123 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - alternate - appendix - archives - author - bookmark - chapter - contents - copyright - current - describedby - edit - edit-media - first - glossary - help - hub - icon - index - last - latest-version - license - monitor - monitor-group - next - next-arvhice - nofollow - payment - predecessor-version - prefetch - prev - previous - prev-archive - replies - search - section - self - service - start - stylesheet - subsection - successor-version - up - version-history - via - working-copy - working-copy-of - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/os_doc_tools/resources/rackbook.rng b/os_doc_tools/resources/rackbook.rng deleted file mode 100644 index 5b7d99ab..00000000 --- a/os_doc_tools/resources/rackbook.rng +++ /dev/null @@ -1,558 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - none - strip - prefix - auto - - - - - - - user - local - near - global - - - - - - - - xml:id required on book, part, section, chapter, appendix, and preface. - - - - - - The fileref attribute on olink must not be empty. - - - - - - - - - - The targetptr and targetdoc attributes on olink must not be empty. - - - - - The primary, secondary, and tertiary elements must not be empty. - - - - - The remark element must not be empty. - - - - - The filename element must not be empty. - - - - - The code element must not be empty. - - - - - The title element must not be empty or conditioned out. - - - - - The procedure element must have a title that begins with 'To'. - - - - - The security attribute should be put on the ancestor listitem. - - - - - The security attribute should be put on the ancestor step. - - - - - The revisionflag=deleted attribute should be put on the ancestor listitem or step. - - - - - The indexterm element must not have a role attribute - - - - - - Please use HTML tables instead of CALS tables. - - - - - - Any attribute including in any attribute in any namespace. - - - - -
- - - Any element from the SVG namespace - - - - - - - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - DELETE - GET - HEAD - POST - PUT - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - plain - query - matrix - header - template - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - [A-Za-z]{1,8}(-[A-Za-z0-9]{1,8})* - - - - diff --git a/os_doc_tools/resources/wadl.rng b/os_doc_tools/resources/wadl.rng deleted file mode 100644 index 8b8a77d5..00000000 --- a/os_doc_tools/resources/wadl.rng +++ /dev/null @@ -1,414 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - DELETE - GET - HEAD - POST - PUT - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - plain - query - matrix - header - template - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - [A-Za-z]{1,8}(-[A-Za-z0-9]{1,8})* - - - diff --git a/os_doc_tools/resources/wadl.xsd b/os_doc_tools/resources/wadl.xsd deleted file mode 100644 index b476fb4c..00000000 --- a/os_doc_tools/resources/wadl.xsd +++ /dev/null @@ -1,263 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/os_doc_tools/resources/xml.xsd b/os_doc_tools/resources/xml.xsd deleted file mode 100644 index aea7d0db..00000000 --- a/os_doc_tools/resources/xml.xsd +++ /dev/null @@ -1,287 +0,0 @@ - - - - - - -
-

About the XML namespace

- -
-

- This schema document describes the XML namespace, in a form - suitable for import by other schema documents. -

-

- See - http://www.w3.org/XML/1998/namespace.html and - - http://www.w3.org/TR/REC-xml for information - about this namespace. -

-

- Note that local names in this namespace are intended to be - defined only by the World Wide Web Consortium or its subgroups. - The names currently defined in this namespace are listed below. - They should not be used with conflicting semantics by any Working - Group, specification, or document instance. -

-

- See further below in this document for more information about how to refer to this schema document from your own - XSD schema documents and about the - namespace-versioning policy governing this schema document. -

-
-
- - - - - - -
- -

lang (as an attribute name)

-

- denotes an attribute whose value - is a language code for the natural language of the content of - any element; its value is inherited. This name is reserved - by virtue of its definition in the XML specification.

- -
-
-

Notes

-

- Attempting to install the relevant ISO 2- and 3-letter - codes as the enumerated possible values is probably never - going to be a realistic possibility. -

-

- See BCP 47 at - http://www.rfc-editor.org/rfc/bcp/bcp47.txt - and the IANA language subtag registry at - - http://www.iana.org/assignments/language-subtag-registry - for further information. -

-

- The union allows for the 'un-declaration' of xml:lang with - the empty string. -

-
- - - - - - - - - - - - - - - - -
- -

space (as an attribute name)

-

- denotes an attribute whose - value is a keyword indicating what whitespace processing - discipline is intended for the content of the element; its - value is inherited. This name is reserved by virtue of its - definition in the XML specification.

- -
- - - - - - - - - - - - -
- -

base (as an attribute name)

-

- denotes an attribute whose value - provides a URI to be used as the base for interpreting any - relative URIs in the scope of the element on which it - appears; its value is inherited. This name is reserved - by virtue of its definition in the XML Base specification.

- -

- See http://www.w3.org/TR/xmlbase/ - for information about this attribute. -

-
- - - - - - - -
- -

id (as an attribute name)

-

- denotes an attribute whose value - should be interpreted as if declared to be of type ID. - This name is reserved by virtue of its definition in the - xml:id specification.

- -

- See http://www.w3.org/TR/xml-id/ - for information about this attribute. -

-
- - - - - - - - - - - - - -
- -

Father (in any context at all)

- -
-

- denotes Jon Bosak, the chair of - the original XML Working Group. This name is reserved by - the following decision of the W3C XML Plenary and - XML Coordination groups: -

-
-

- In appreciation for his vision, leadership and - dedication the W3C XML Plenary on this 10th day of - February, 2000, reserves for Jon Bosak in perpetuity - the XML name "xml:Father". -

-
-
-
- - - - - -
-

About this schema document

- -
-

- This schema defines attributes and an attribute group suitable - for use by schemas wishing to allow xml:base, - xml:lang, xml:space or - xml:id attributes on elements they define. -

-

- To enable this, such a schema must import this schema for - the XML namespace, e.g. as follows: -

- 
-          <schema . . .>
-           . . .
-           <import namespace="http://www.w3.org/XML/1998/namespace"
-                      schemaLocation="http://www.w3.org/2001/xml.xsd"/>
-
-

- or -

- 
-           <import namespace="http://www.w3.org/XML/1998/namespace"
-                      schemaLocation="http://www.w3.org/2009/01/xml.xsd"/>
-
-

- Subsequently, qualified reference to any of the attributes or the - group defined below will have the desired effect, e.g. -

- 
-          <type . . .>
-           . . .
-           <attributeGroup ref="xml:specialAttrs"/>
-
-

- will define a type which will schema-validate an instance element - with any of those attributes. -

-
-
- - - - - -
-

Versioning policy for this schema document

-
-

- In keeping with the XML Schema WG's standard versioning - policy, this schema document will persist at - - http://www.w3.org/2009/01/xml.xsd. -

-

- At the date of issue it can also be found at - - http://www.w3.org/2001/xml.xsd. -

-

- The schema document at that URI may however change in the future, - in order to remain compatible with the latest version of XML - Schema itself, or with the XML namespace itself. In other words, - if the XML Schema or XML namespaces change, the version of this - document at - http://www.w3.org/2001/xml.xsd - - will change accordingly; the version at - - http://www.w3.org/2009/01/xml.xsd - - will not change. -

-

- Previous dated (and unchanging) versions of this schema - document are at: -

- -
-
- - - - - diff --git a/releasenotes/notes/docbook-removal-0c0d6c5a7b73ab77.yaml b/releasenotes/notes/docbook-removal-0c0d6c5a7b73ab77.yaml new file mode 100644 index 00000000..ccec4bda --- /dev/null +++ b/releasenotes/notes/docbook-removal-0c0d6c5a7b73ab77.yaml @@ -0,0 +1,6 @@ +--- +prelude: > + The most important change in this release is the removal + of DocBook XML support. Support for checking, building, and + translation of DocBook XML files has been removed. The tools now + only handle RST files. diff --git a/setup.cfg b/setup.cfg index 64df873f..2de46b83 100644 --- a/setup.cfg +++ b/setup.cfg @@ -37,7 +37,6 @@ setup-hooks = [entry_points] console_scripts = - openstack-doc-test = os_doc_tools.doctest:doctest openstack-auto-commands = os_doc_tools.commands:main openstack-jsoncheck = os_doc_tools.jsoncheck:main openstack-indexpage = os_doc_tools.index:main