From 1399099d400aaa91daae113854889e448ca6a67d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ren=C3=A9=20Ferdinand=20Rivera=20Morell?= Date: Fri, 15 Nov 2024 14:08:35 -0600 Subject: [PATCH] Convert to Asciidoctor sources. (#7) --- .github/workflows/draft.yml | 6 +- .github/workflows/static.yml | 18 + .gitignore | 3 + README.adoc | 30 +- build.jam | 75 ++- pub/std_info-1.0.0.json | 2 +- pub/std_param-1.0.0.json | 83 ++++ src/asciidoctor-latexcore/build.jam | 19 + src/asciidoctor-latexcore/latexcore.rb | 475 +++++++++++++++++++ src/build.jam | 93 ++++ src/eco_back_biblio.adoc | 17 + src/eco_back_biblio.tex | 20 +- src/eco_back_index.adoc | 16 + src/eco_back_index.tex | 12 + src/eco_back_xref.adoc | 25 + src/{eco_back.tex => eco_back_xref.tex} | 14 +- src/eco_conformance.adoc | 13 + src/eco_conformance.tex | 9 +- src/eco_cover_reg.adoc | 162 +++++++ src/eco_cover_reg.tex | 9 +- src/eco_cover_wd.adoc | 55 +++ src/eco_cover_wd.tex | 25 +- src/eco_defs.adoc | 90 ++++ src/eco_defs.tex | 80 ++-- src/eco_diag.adoc | 12 + src/eco_diag.tex | 16 + src/eco_front.tex | 35 -- src/eco_introspection.adoc | 385 ++++++++++++++++ src/eco_introspection.tex | 276 ++++++----- src/eco_introspection_annex.adoc | 34 ++ src/eco_introspection_annex.tex | 34 +- src/eco_license.adoc | 381 ++++++++++++++++ src/eco_license.tex | 584 ++++++++++++------------ src/eco_preface.adoc | 54 +++ src/eco_preface.tex | 24 +- src/eco_preface_changes.adoc | 9 + src/eco_preface_changes.tex | 11 +- src/eco_refs.adoc | 31 ++ src/eco_refs.tex | 31 +- src/eco_scope.adoc | 16 + src/eco_scope.tex | 12 +- src/eco_strctparam.adoc | 206 +++++++++ src/eco_strctparam.tex | 272 +++++++++++ src/eco_strctparam_annex.adoc | 34 ++ src/eco_strctparam_annex.tex | 112 +++++ src/eco_strctparam_core.adoc | 21 + src/eco_strctparam_core.tex | 28 ++ src/ecosystem.adoc | 87 ++++ src/ecosystem.tex | 42 +- src/in_config.adoc | 33 ++ src/in_config.tex | 30 +- src/in_html.css | 130 ++++++ src/in_macros.tex | 3 +- src/in_vars.adoc | 39 ++ 54 files changed, 3667 insertions(+), 666 deletions(-) create mode 100644 pub/std_param-1.0.0.json create mode 100644 src/asciidoctor-latexcore/build.jam create mode 100644 src/asciidoctor-latexcore/latexcore.rb create mode 100644 src/build.jam create mode 100644 src/eco_back_biblio.adoc create mode 100644 src/eco_back_index.adoc create mode 100644 src/eco_back_index.tex create mode 100644 src/eco_back_xref.adoc rename src/{eco_back.tex => eco_back_xref.tex} (69%) create mode 100644 src/eco_conformance.adoc create mode 100644 src/eco_cover_reg.adoc create mode 100644 src/eco_cover_wd.adoc create mode 100644 src/eco_defs.adoc create mode 100644 src/eco_diag.adoc create mode 100644 src/eco_diag.tex delete mode 100644 src/eco_front.tex create mode 100644 src/eco_introspection.adoc create mode 100644 src/eco_introspection_annex.adoc create mode 100644 src/eco_license.adoc create mode 100644 src/eco_preface.adoc create mode 100644 src/eco_preface_changes.adoc create mode 100644 src/eco_refs.adoc create mode 100644 src/eco_scope.adoc create mode 100644 src/eco_strctparam.adoc create mode 100644 src/eco_strctparam.tex create mode 100644 src/eco_strctparam_annex.adoc create mode 100644 src/eco_strctparam_annex.tex create mode 100644 src/eco_strctparam_core.adoc create mode 100644 src/eco_strctparam_core.tex create mode 100644 src/ecosystem.adoc create mode 100644 src/in_config.adoc create mode 100644 src/in_html.css create mode 100644 src/in_vars.adoc diff --git a/.github/workflows/draft.yml b/.github/workflows/draft.yml index 03880b2..1d8104f 100644 --- a/.github/workflows/draft.yml +++ b/.github/workflows/draft.yml @@ -20,15 +20,15 @@ jobs: run: sudo apt-get update - name: Install (APT) - run: sudo apt-get install latexmk texlive-latex-recommended texlive-latex-extra texlive-fonts-recommended lmodern + run: sudo apt-get install latexmk texlive-latex-recommended texlive-latex-extra texlive-fonts-recommended lmodern asciidoctor - name: Install (B2) run: | set -e pushd .. - wget "https://github.com/bfgroup/b2/archive/release.zip" -O b2.zip + wget "https://github.com/bfgroup/b2/archive/main.zip" -O b2.zip unzip b2.zip - cd b2-release + cd b2-main CXX= ./bootstrap.sh CXX= sudo ./b2 install b2-install-layout=portable --prefix=/usr/bin popd diff --git a/.github/workflows/static.yml b/.github/workflows/static.yml index ef45fc1..7053be6 100644 --- a/.github/workflows/static.yml +++ b/.github/workflows/static.yml @@ -28,6 +28,7 @@ concurrency: jobs: # Single deploy job since we're just deploying deploy: + if: github.repository == 'cplusplus/ecosystem-is' environment: name: github-pages url: ${{ steps.deployment.outputs.page_url }} @@ -35,6 +36,23 @@ jobs: steps: - name: Checkout uses: actions/checkout@main + - name: Update APT Cache + run: sudo apt-get update + - name: Install (APT) + run: sudo apt-get install asciidoctor + - name: Install (B2) + run: | + set -e + pushd .. + wget "https://github.com/bfgroup/b2/archive/main.zip" -O b2.zip + unzip b2.zip + cd b2-main + CXX= ./bootstrap.sh + CXX= sudo ./b2 install b2-install-layout=portable --prefix=/usr/bin + popd + - name: Build (Web) + run: | + b2 --debug-configuration -d+2 ecosystem-pub - name: Setup Pages uses: actions/configure-pages@main - name: Upload artifact diff --git a/.gitignore b/.gitignore index a8c5878..00cea58 100644 --- a/.gitignore +++ b/.gitignore @@ -237,3 +237,6 @@ report/*.html # Build dirs /.build + +/ecosystem-is-*.* +/pub/index.html diff --git a/README.adoc b/README.adoc index 5c9ca62..a36b066 100644 --- a/README.adoc +++ b/README.adoc @@ -16,6 +16,17 @@ involved in the development you can: == Getting Started +=== Asciidoctor + +You'll need the latest https://asciidoctor.org/[Asciidoctor] version 2. Consult +their https://asciidoctor.org/#installation[installation] instructions for ways +to obtain it. + +=== B2 + +The https://www.bfgroup.xyz/b2/[B2] build system is needed to manage the +translation steps from the Asciidoctor sources, to LaTex+PDF and to HTML. + === LaTeX You'll need a sufficiently recent and capable LaTeX distribution installed and @@ -69,22 +80,3 @@ you have the appropriate LaTeX tools installed and accessible vscode will automatically build a PDF you can preview in vscode and edit `tex` files semi-live. The resulting built files and PDF are placed in the `${workspaceFolder}/.build/vscode` directory. - -=== B2 - -You can use the https://www.bfgroup.xyz/b2/[B2 build system] which has more -ways to build the documents. Obviously you'll need to install LaTeX as above. -And of course also install B2, if you don't already have it. Then you can just -do: `b2` at the root to produce the default draft PDF. - -=== Manual - -It's also possible to directly build the PDF doc from the command line: - -[source,shell] ----- -cd src -latexmk -pdf ecosystem.tex ----- - -Which will produce many files and a `ecosystem.pdf` result in the current dir. diff --git a/build.jam b/build.jam index 61940c3..641320f 100644 --- a/build.jam +++ b/build.jam @@ -1,65 +1,62 @@ +#| +Copyright René Ferdinand Rivera Morell +Distributed under the Boost Software License, Version 1.0. +(See accompanying file LICENSE_1_0.txt or copy at +http://www.boost.org/LICENSE_1_0.txt) +|# + +require-b2 5.3 ; + import toolset ; import feature ; -feature.feature doc-stage : draft final : propagated symmetric ; +feature.feature doc-stage : draft final web : propagated symmetric ; feature.feature verbose : off on : propagated incidental ; feature.feature license : off on : propagated symmetric ; -project /ecosystem +project /cplusplus/ecosystem-is : build-dir .build/b2 + : default-build draft off on ; -local tex-src = [ glob src/eco_*.tex src/in_*.tex src/*.ist ] ; -local latexmkrc = [ glob src/*latexmkrc* ] ; -local _ = " " ; - -rule latex-defs ( properties * ) +rule install-name-pdf ( properties * ) { - local pretex ; - if final in $(properties) - { - pretex += "\\\\def\\\\isofinal{yes}" ; - } - if on in $(properties) - { - pretex += "\\\\def\\\\license{yes}" ; - } - return "-usepretex=\"$(pretex:J= )\"" ; + local name = ecosystem-is ; + if draft in $(properties) { name += draft ; } + if final in $(properties) { name += final ; } + if on in $(properties) { name += ccby4 ; } + return $(name:J=-).pdf ; } -make ecosystem.pdf : src/ecosystem.tex - : @latexmk - : $(tex-src) - on:-verbose - on:-diagnostics - -r$(_)"$(latexmkrc[1])" - @latex-defs +install ecosystem-is-latex-pdf + : src//ecosystem.pdf + : . + @install-name-pdf doc-stage license ; -explicit ecosystem.pdf ; -rule install-name ( properties * ) +rule install-name-html ( properties * ) { local name = ecosystem-is ; if draft in $(properties) { name += draft ; } if final in $(properties) { name += final ; } if on in $(properties) { name += ccby4 ; } - return $(name:J=-).pdf ; + return $(name:J=-).html ; } -install ecosystem-is - : ecosystem.pdf +install ecosystem-is-adoc-html + : src//ecosystem.html : . - @install-name + @install-name-html + doc-stage + license ; -# Generic latexmk action. - -toolset.flags $(__name__).latexmk FLAGS ; - -actions latexmk -{ - export TEXINPUTS="$(>:D):${TEXINPUTS}" - latexmk -f -pdf -interaction=nonstopmode -logfilewarnings- -shell-escape -gg -outdir="$(<:D)" -auxdir="$(<:D)" -makeindexfudge $(FLAGS) "$(>:D=)" -} +install ecosystem-pub + : src//ecosystem.html/web/on + : pub + index.html + doc-stage + license + ; diff --git a/pub/std_info-1.0.0.json b/pub/std_info-1.0.0.json index 3b716f5..90a1938 100644 --- a/pub/std_info-1.0.0.json +++ b/pub/std_info-1.0.0.json @@ -1,6 +1,6 @@ { "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://cplusplus.github.io/ecosystem-is/std_info-1.0.0.json", + "$id": "std_info-1.0.0.json", "title": "Tool Introspection Version 1.0.0 JSON Schema", "$defs": { "VersionMin": { diff --git a/pub/std_param-1.0.0.json b/pub/std_param-1.0.0.json new file mode 100644 index 0000000..c347892 --- /dev/null +++ b/pub/std_param-1.0.0.json @@ -0,0 +1,83 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "std_param-1.0.0.json", + "title": "Structured Parameters Version 1.0.0 JSON Schema", + "type": "object", + "properties": { + "$schema": { + "description": "JSON Schema URI for the version of the structured parameters format.", + "type": "string", + "format": "uri" + }, + "version": { + "description": "The Structured Parameters format version.", + "type": "string", + "$ref": "#/$defs/Version" + }, + "arguments": { + "description": "Application direct arguments.", + "type": "array", + "items": { + "type": "string" + } + }, + "options": { + "description": "Application structured options.", + "type": "object", + "allOf": [ + { + "$ref": "#/$opt/Std.Param" + } + ], + "propertyName": { + "$ref": "#/$defs/Name" + } + } + }, + "oneOf": [ + { + "required": ["arguments"] + }, + { + "required": ["options"] + } + ], + "$defs": { + "Version": { + "type": "string", + "pattern": "^[0-9]+([.][0-9]+){0,2}$" + }, + "Name": { + "type": "string", + "pattern": "^([a-z0-9_-]+[.])*([a-z0-9_-]+)$" + }, + "StringOrArray": { + "type": ["string", "array"], + "items": { + "type": "string" + } + } + }, + "$opt": { + "Std.Param": { + "properties": { + "std.param": { + "description": "Recursive reference to one or more structured parameters files.", + "type": "object", + "properties": { + "pre": { + "$ref": "#/$defs/StringOrArray" + }, + "post": { + "$ref": "#/$defs/StringOrArray" + } + }, + "additionalProperties": false + } + }, + "param": { + "$ref": "#/$opt/Std.Param/properties/std.param" + } + } + } +} diff --git a/src/asciidoctor-latexcore/build.jam b/src/asciidoctor-latexcore/build.jam new file mode 100644 index 0000000..dc0a960 --- /dev/null +++ b/src/asciidoctor-latexcore/build.jam @@ -0,0 +1,19 @@ +#| +Copyright René Ferdinand Rivera Morell +Distributed under the Boost Software License, Version 1.0. +(See copy at http://www.boost.org/LICENSE_1_0.txt) +|# + +require-b2 5.2 ; + +project /grafikrobot/asciidoctor-latexcore ; + +path-constant here : . ; + +alias latexcore + : usage-requirements + "-r $(here)/latexcore.rb" + "-b latexcore" + latexcore.rb + ; +explicit latexcore ; diff --git a/src/asciidoctor-latexcore/latexcore.rb b/src/asciidoctor-latexcore/latexcore.rb new file mode 100644 index 0000000..4e093cc --- /dev/null +++ b/src/asciidoctor-latexcore/latexcore.rb @@ -0,0 +1,475 @@ +# frozen_string_literal: true + +require 'cgi' + +module AsciidoctorLaTexCore + + class LaTexCoreConverter < Asciidoctor::Converter::Base + register_for 'latexcore' + + LF = "\n" + + IGNORED_SCOPES = Set[ + # Built-in roles + # 'underline', + 'overline', + 'line-through', + 'nobreak', + 'nowrap', + 'pre-wrap', + # Common roles + 'right' + ] + + def initialize backend, opts = {} + @backend = backend + init_backend_traits basebackend: 'latexcore', filetype: 'tex', outfilesuffix: '.tex', supports_templates: true + end + + def convert_document node + @tex_index = node.attr 'texindex' + @in_literal = 0 + @in_bibliography = 0 + @tex_source_highlighter = node.attr 'tex-source-highlighter' + + tex_root = node.attr 'texroot' + + # root name + result = [] + result << %(\ +\%!TEX root = #{tex_root} +) if tex_root + + result << %(\ +% Generated file. Do not edit. +) + + copyright = node.attr 'copyright' + license = node.attr 'license' + if copyright || license + if copyright + result << %(% #{copyright}) + end + if license + result << %(% #{license}) + end + result << %() + end + + if node.title + if ! node.attr? 'texbare' + if role?(node, 'chapter') + # plain chapter + result << %(\ +\\chapter{#{texify(node.title.strip)}} +) + else + # section 0 + result << gen_section_title(node) + end + end + end + + # content + result << %(\ +#{node.content}) + + result.join LF + end + + def convert_embedded node + result = [] + result << node.content + result.join LF + end + + def convert_section node + result = [] + result << gen_section_title(node) + result << %(\ +#{node.content}) + result.join LF + end + + def convert_admonition node + result = [] + name = (node.role) ? (node.role[0]) : (node.attr 'name') + result << %(\ +\\begin{#{name}} +#{node.content} +\\end{#{name}} +) + result.join LF + end + + def convert_colist node + result = [] + result.join LF + end + + def convert_dlist node + result = [] + is_bnf = node.option?('bnf') || role?(node,'bnf') + if is_bnf + result << %(\\begin{bnf}) + elsif node.option?('description') + result << %(\\begin{description}) + end + node.items.each do |terms, dd| + if is_bnf + result << %(\n\\nontermdef{#{terms[0].text}}\\br) + result << texify(dd.text.gsub("\n", "\\br\n")) if dd.text? + result << dd.content.join("\\br\n") if dd.blocks? + elsif node.option?('description') + result << %(\\item[#{texify(terms[0].text)}] #{texify(dd.text.gsub("\n", "\\br\n"))}) if dd.text? + result << %(\\item[#{texify(terms[0].text)}] #{dd.content.join("\\br\n")}) if dd.blocks? + else + result << %(\n\\definition{#{terms[0].text}}{#{node.id}}) + result << texify(dd.text) if dd.text? + result << dd.content if dd.blocks? + end + end + if is_bnf + result << %(\\end{bnf}) + elsif node.option?('description') + result << %(\\end{description}) + end + result.join LF + end + + def convert_example node + result = [] + result << %(\ +\\begin{example} +#{texify(node.content)} +\\end{example} +) + result.join LF + end + + def convert_floating_title node + result = [] + result.join LF + end + + def convert_image node + result = [] + result.join LF + end + + def convert_listing node + result = [] + lst_lang = '' + lst_tag = '' + if node.attributes.key? 'language' + lst_lang = node.attributes['language'] + end + lst_args = '' + if @tex_source_highlighter == 'minted' + lst_tag = 'minted' + lst_args = %({#{lst_lang}}) + elsif @tex_source_highlighter == 'listings' + lst_tag = 'lstlisting' + # lst_args = %([language=#{lst_lang}]) + end + result << %( +\\begin{#{lst_tag}}#{lst_args} +#{texify(node.content)} +\\end{#{lst_tag}} +) + result.join LF + end + + def convert_literal node + @in_literal += 1 + result = [] + if ! node.option?('nonum') + result << %(\\pnum) + end + lst_tag = '' + lst_args = '' + if @tex_source_highlighter == 'minted' + lst_tag = 'minted' + lst_args = '{}' + elsif @tex_source_highlighter == 'listings' + lst_tag = 'lstlisting' + end + result << %(\ +\\begin{#{lst_tag}}{} +#{texify(node.content)} +\\end{#{lst_tag}} +) + result.join LF + @in_literal -= 1 + result + end + + def convert_sidebar node + result = [] + result.join LF + end + + def convert_olist node + result = [] + if node.option?('bibliography') + @in_bibliography += 1 + end + options = [] + # result << %(% #{node.list_marker_keyword}) + if node.list_marker_keyword == 'a' + options << %(label=\\alph*.) + elsif node.list_marker_keyword == 'A' + options << %(label=\\Alph*.) + elsif node.list_marker_keyword == 'i' + options << %(label=\\roman*.) + elsif node.list_marker_keyword == 'I' + options << %(label=\\Roman*.) + else + options << %(label=\\arabic*.) + end + result << "\\begin{enumerate}[#{options.join ", "}]\n" + node.items.map do |item| + result << %(\\item #{texify(item.text)}\n) if item.text? + result << texify(item.content) if item.blocks? + end + result << "\\end{enumerate}\n" + if node.option?('bibliography') + @in_bibliography -= 1 + end + result.join LF + end + + def convert_open node + result = [] + if role?(node) + result << %(\\begin{#{role?(node)}}) + end + result << texify(node.content) + if role?(node) + result << %(\\end{#{role?(node)}}\n) + end + result.join LF + end + + def convert_page_break node + '\\newpage\n' + end + + def convert_paragraph node + result = [] + if role?(node, 'itemdescr') + result << %( +\\begin{itemdescr} +#{texify(node.content).gsub(/\\pnum/, "\n\\pnum")} +\\end{itemdescr} +) + elsif node.option?('nonum') + result << %(\ +#{texify(node.content)} +) + else + result << %(\ +\\pnum +#{texify(node.content)} +) + end + result.join LF + end + + alias convert_pass content_only + alias convert_preamble content_only + + def convert_quote node + result = [] + result.join LF + end + + def convert_stem node + result = [] + result.join LF + end + + def convert_table node + result = [] + result.join + end + + def convert_thematic_break node + end + + alias convert_toc skip + + def convert_ulist node + result = [] + result << "\\begin{itemize}\n" + node.items.map do |item| + result << %(\\item #{texify(item.text)}\n) + end + result << "\\end{itemize}\n" + result.join LF + end + + def convert_verse node + result = [] + result.join LF + end + + alias convert_video skip + + def convert_inline_anchor node + case node.type + when :xref + node_refid = node.attributes['refid'] + root_doc = get_root_document node + ref = root_doc.resolve_id(node_refid) + iref = ref ? ref.xreftext : (node.text ? node.text : node_refid) + %((\\ref{#{texify_iref(iref)}})) + when :link + if node.option?('input') + %(\\input{#{node.target}}) + elsif node.target.start_with?("mailto:") + node.text + else + %(\\url{#{node.target}}) + end + when :ref + %(\\label{#{node.id}}) + when :bibref + %(\\label{#{node.id}}) + else + logger.warn %(unknown anchor type: #{node.type.inspect}) + nil + end + end + + def convert_inline_break node + %(#{node.text}) + end + + alias convert_inline_button skip + + def convert_inline_callout node + %(#{node.text}) + end + + def convert_inline_footnote node + %(#{node.text}) + end + + alias convert_inline_image skip + + def convert_inline_indexterm node + if node.type == :visible + %(\\index[#{@tex_index}]{#{texify(node.text)}}#{texify(node.text)}) + else + %(\\index[#{@tex_index}]{#{texify(node.attr('terms')[0])}}) + end + end + + def convert_inline_kbd node + end + + def convert_inline_menu node + end + + def convert_inline_quoted node + q = (@in_literal > 0) ? "@" : "" + case node.type + when :emphasis + %(#{q}\\emph{#{texify(node.text)}}#{q}) + when :strong + %(#{q}\\textbf{#{texify(node.text)}}#{q}) + when :monospaced + %(#{q}\\verb|#{texify(node.text)}|#{q}) + when :single + %(‘#{texify(node.text)}’) + when :double + %(“#{texify(node.text)}”) + else + if IGNORED_SCOPES.include?(role?(node)) + nil + elsif role?(node, 'iref') + %(#{q}\\ref{#{texify_iref(node.text)}}#{q}) + elsif role?(node, 'fldname') + %(#{q}\\pnum#{q} #{q}\\fldname#{q}) + elsif role?(node, 'fldtype') + %(#{q}\\pnum#{q} #{q}\\fldtype#{q}) + elsif role?(node, 'fldval') + %(#{q}\\pnum#{q} #{q}\\fldval#{q}) + elsif role?(node, 'flddesc') + %(#{q}\\pnum#{q} #{q}\\flddesc#{q}) + elsif role?(node, 'item') + %(#{q}\\item[#{texify_iref(node.text)}]#{q}) + elsif role?(node, 'Cpp') + %(#{q}\\Cpp{}#{q}) + elsif role? node + %(#{q}\\#{role? node}{#{texify(node.text)}}#{q}) + else + texify(node.text) + end + end + end + + private + + def texify str + if str + str.gsub(/&#([0-9]+);/){ $1.to_i.chr(Encoding::UTF_8) }.rstrip + .gsub(/</){ '<' } + .gsub(/>/){ '>' } + else + '' + end + end + + def texify_iref str + str = texify(str).sub(/^\(\[/,'').sub(/\]\)$/,'') + end + + def get_root_document node + while (node = node.document).nested? + node = node.parent_document + end + node + end + + def role? node, role_name = nil + if role_name + (node.has_role? role_name) ? role_name : nil + elsif node.role + node.roles[0] + else + nil + end + end + + def gen_section_title node + result = [] + node_level = node.level - (node.document.attributes['leveldedent'] || '0').to_i + node_ref = node.id + # node_ref = node.reftext if node.reftext? + node_title = node.title.strip + if role?(node, 'ignore') + nil + elsif role?(node, 'infannex') + result << %(\ +\% #{node_title} +\\infannex{#{node_ref}}{#{node_title}} +) + else + result << %(\ +\% #{node_title} +\\rSec#{node_level}[#{node_ref}]{#{node_title}} +) + end + return result + end + end + +end # AsciidoctorLaTexCore + +=begin +Copyright René Ferdinand Rivera Morell +Distributed under the Boost Software License, Version 1.0. +(See copy at http://www.boost.org/LICENSE_1_0.txt) +=end diff --git a/src/build.jam b/src/build.jam new file mode 100644 index 0000000..bd9983a --- /dev/null +++ b/src/build.jam @@ -0,0 +1,93 @@ +#| +Copyright René Ferdinand Rivera Morell +Distributed under the Boost Software License, Version 1.0. +(See accompanying file LICENSE_1_0.txt or copy at +http://www.boost.org/LICENSE_1_0.txt) +|# + +require-b2 5.3 ; + +import toolset ; +import feature ; +using asciidoctor ; + +# Build LaTex from Asciidoctor.. + +feature.feature asciidoctor-latexcore.flags : : free optional ; +toolset.flags $(__name__).asciidoctor-latexcore FLAGS : ; + +actions asciidoctor-latexcore +{ + asciidoctor -o$(_)"$(<:D=)" -D$(_)"$(<:D)" $(FLAGS) "$(>)" --trace --warnings --verbose +} + +local tex-parts ; +for local adoc in [ glob eco_*.adoc in_config.adoc ] +{ + tex-parts += [ make $(adoc:B).tex + : $(adoc) + : @asciidoctor-latexcore + : requirements + ./asciidoctor-latexcore//latexcore + . + ] ; +} +alias tex : $(tex-parts) ; + +# Build HTML from Asciidoctor.. + +html ecosystem.html : ecosystem.adoc + : draft:docstage=draft + final:docstage=final + web:docstage=web + on:doclicense=on + doc-stage + license + ; +explicit ecosystem.html ; + +# Build PDF from LaTex.. + +feature.feature latexmk.flags : : free optional ; +toolset.flags $(__name__).latexmk FLAGS ; + +actions latexmk +{ + export TEXINPUTS="$(>:D):${TEXINPUTS}" + latexmk -f -pdf -interaction=nonstopmode -logfilewarnings- -shell-escape -gg -outdir="$(<:D)" -auxdir="$(<:D)" -makeindexfudge $(FLAGS) "$(>:D=)" +} + +local adoc-src = [ glob eco_*.adoc ] ; +local tex-src = [ glob eco_*.tex in_*.tex *.ist ] ; +local latexmkrc-src = [ glob *latexmkrc* ] ; +local _ = " " ; + +path-constant latexmkrc : $(latexmkrc-src[1]) ; + +rule latex-defs ( properties * ) +{ + local pretex ; + if final in $(properties) + { + pretex += "\\\\def\\\\isofinal{yes}" ; + } + if on in $(properties) + { + pretex += "\\\\def\\\\license{yes}" ; + } + return "-usepretex=\"$(pretex:J= )\"" ; +} + +make ecosystem.pdf : ecosystem.tex + : @latexmk + : tex + # $(adoc-src) + # $(tex-src) + on:-verbose + on:-diagnostics + -r$(_)"$(latexmkrc)" + @latex-defs + doc-stage + license + ; +explicit ecosystem.pdf ; diff --git a/src/eco_back_biblio.adoc b/src/eco_back_biblio.adoc new file mode 100644 index 0000000..ba4c746 --- /dev/null +++ b/src/eco_back_biblio.adoc @@ -0,0 +1,17 @@ +include::in_vars.adoc[] +[.text-justify.chapter] +[[bib,([bib])]] += Bibliography +:copyright: Copyright {docyear} René Ferdinand Rivera Morell +:license: Creative Commons Attribution 4.0 International License (CC BY 4.0) + +// Groups, in order: +// . ISO documents in numerical order. +// . Other international standards. +// . Literature references. + +[%bibliography] +. Internet Engineering Task Force. + IETF RFC draft _JSON Schema: A Media Type for Describing JSON Documents_. + Available from: https://json-schema.org/draft/2020-12/json-schema-core.html + [[jsonschema,([jsonschema])]] diff --git a/src/eco_back_biblio.tex b/src/eco_back_biblio.tex index 20bd21b..d591502 100644 --- a/src/eco_back_biblio.tex +++ b/src/eco_back_biblio.tex @@ -1,15 +1,17 @@ %!TEX root = ecosystem.tex -\chapter{Bibliography} +% Generated file. Do not edit. + +% Copyright 2024 René Ferdinand Rivera Morell +% Creative Commons Attribution 4.0 International License (CC BY 4.0) -\begin{itemize} - \renewcommand{\labelitemi}{---} +\chapter{Bibliography} - % ISO documents in numerical order. - \item - ISO xxxx:YYYY, - \doccite{Title} +\begin{enumerate}[label=\arabic*.] - % Other international standards. +\item Internet Engineering Task Force. +IETF RFC draft \emph{JSON Schema: A Media Type for Describing JSON Documents}. +Available from: \url{https://json-schema.org/draft/2020-12/json-schema-core.html} +\label{jsonschema} -\end{itemize} +\end{enumerate} diff --git a/src/eco_back_index.adoc b/src/eco_back_index.adoc new file mode 100644 index 0000000..8f5ff95 --- /dev/null +++ b/src/eco_back_index.adoc @@ -0,0 +1,16 @@ +include::in_vars.adoc[] +:copyright!: +:license!: + +ifeval::["{backend}" == "latexcore"] +++++ +% Index +\clearpage +\renewcommand{\leftmark}{\indexname} +\renewcommand{\preindexhook}{Constructions whose name appears in \exposid{monospaced italics} are for exposition only.\\} +{ +\raggedright +\printindex[generalindex] +} +++++ +endif::[] diff --git a/src/eco_back_index.tex b/src/eco_back_index.tex new file mode 100644 index 0000000..3086f2c --- /dev/null +++ b/src/eco_back_index.tex @@ -0,0 +1,12 @@ +%!TEX root = ecosystem.tex + +% Generated file. Do not edit. + +% Index +\clearpage +\renewcommand{\leftmark}{\indexname} +\renewcommand{\preindexhook}{Constructions whose name appears in \exposid{monospaced italics} are for exposition only.\\} +{ +\raggedright +\printindex[generalindex] +} \ No newline at end of file diff --git a/src/eco_back_xref.adoc b/src/eco_back_xref.adoc new file mode 100644 index 0000000..67db767 --- /dev/null +++ b/src/eco_back_xref.adoc @@ -0,0 +1,25 @@ +include::in_vars.adoc[] +:copyright!: +:license!: + +ifeval::["{backend}" == "latexcore"] +++++ +% Cross references +% FIXME: For unknown reasons, hanging paragraphs are not indented within our +% glossaries by default. +\let\realglossitem\glossitem +\renewcommand{\glossitem}[4]{\hangpara{4em}{1}\realglossitem{#1}{#2}{#3}{#4}} + +\clearpage +\renewcommand{\glossaryname}{Cross references} +\renewcommand{\preglossaryhook}{Each clause and subclause label is listed below +along with the corresponding clause or subclause number and page number, in +alphabetical order by label.\\} +\twocolglossary +\renewcommand{\leftmark}{\glossaryname} +{ +\raggedright +\printglossary[xrefindex] +} +++++ +endif::[] diff --git a/src/eco_back.tex b/src/eco_back_xref.tex similarity index 69% rename from src/eco_back.tex rename to src/eco_back_xref.tex index b8fedbd..b6e8324 100644 --- a/src/eco_back.tex +++ b/src/eco_back_xref.tex @@ -1,7 +1,6 @@ %!TEX root = ecosystem.tex -% Bibliography -\input{eco_back_biblio} +% Generated file. Do not edit. % Cross references % FIXME: For unknown reasons, hanging paragraphs are not indented within our @@ -19,13 +18,4 @@ { \raggedright \printglossary[xrefindex] -} - -% Index -\clearpage -\renewcommand{\leftmark}{\indexname} -\renewcommand{\preindexhook}{Constructions whose name appears in \exposid{monospaced italics} are for exposition only.\\} -{ -\raggedright -\printindex[generalindex] -} +} \ No newline at end of file diff --git a/src/eco_conformance.adoc b/src/eco_conformance.adoc new file mode 100644 index 0000000..edf4c54 --- /dev/null +++ b/src/eco_conformance.adoc @@ -0,0 +1,13 @@ +include::in_vars.adoc[] +[.text-justify] +[[intro.cnf,([intro.cnf])]] += Conformance [.right]#<># +:copyright: Copyright {docyear} René Ferdinand Rivera Morell +:license: Creative Commons Attribution 4.0 International License (CC BY 4.0) + +(((conformance))) +A conforming implementation shall meet the following criteria for conformance +to this standard: + +* An application shall support the minimum level functionality of +introspection <>. diff --git a/src/eco_conformance.tex b/src/eco_conformance.tex index 5fa3489..8cf0760 100644 --- a/src/eco_conformance.tex +++ b/src/eco_conformance.tex @@ -1,14 +1,21 @@ %!TEX root = ecosystem.tex +% Generated file. Do not edit. + +% Copyright 2024 René Ferdinand Rivera Morell +% Creative Commons Attribution 4.0 International License (CC BY 4.0) + +% Conformance \rSec0[intro.cnf]{Conformance} \pnum +\index[generalindex]{conformance} A conforming implementation shall meet the following criteria for conformance to this standard: \begin{itemize} \item An application shall support the minimum level functionality of -introspection \iref{intspct.min}. +introspection (\ref{intspct.min}). \end{itemize} diff --git a/src/eco_cover_reg.adoc b/src/eco_cover_reg.adoc new file mode 100644 index 0000000..b1a579d --- /dev/null +++ b/src/eco_cover_reg.adoc @@ -0,0 +1,162 @@ +include::in_vars.adoc[] +:copyright!: +:license!: + +ifeval::["{backend}" == "latexcore"] +++++ +%%-------------------------------------------------- +%% Title page + +\setlength{\fboxsep}{1em} +\newlength{\copyboxwidth} +\setlength{\copyboxwidth}{\textwidth} +\addtolength{\copyboxwidth}{-2\fboxsep} +\addtolength{\copyboxwidth}{-2\fboxrule} + +\thispagestyle{empty} +% {\raisebox{.35ex}{\smaller\copyright}}\,ISO/IEC \relyear --- CC BY 4.0 +% \vspace{2ex} + +\begin{flushright} +\textbf{ISO/IEC JTC1 SC22 WG21 \LARGE\docno} + +Date: \reldate + +ISO/IEC DIS \disno + +ISO/IEC JTC1 SC22 + +Secretariat: ANSI + +\end{flushright} + +\vfill + +\textbf{\LARGE \doctitleen} + +\doctitlefr + +\vfill + +\fbox{% +\begin{minipage}{\copyboxwidth} +\vspace{1ex} +\begin{center} +\textbf{WARNING} +\end{center} +\vspace{2ex} + +This document is not an ISO International Standard. It is distributed for +review and comment. It is subject to change without notice and may not be +referred to as an International Standard.\\[1em] + +Recipients of this draft are invited to submit, with their comments, +notification of any relevant patent rights of which they are aware and to +provide supporting documentation.\\ +\end{minipage}} + +\vfill +\noindent +Document reference number: \isodocno{}\\ +Document type: \isodoctype{}\\ +Document stage: \isodocstage{}\\ +Document Language: E\\ + +\isocopyright +\pagebreak + +% \thispagestyle{cpppage} + +\vfill +\fbox{% +\begin{minipage}{\copyboxwidth} +\vspace{1ex} +% \begin{center} +% \textbf{COPYRIGHT PROTECTED DOCUMENT} +% \end{center} +% \vspace{2ex} +% +\copyright\ ISO/IEC \relyear\\ + +\ifdefined\license +Except where otherwise noted, content is licensed under a Creative Commons +Attribution 4.0 International license (CC BY 4.0).\\ +\fi + +\begin{indented} +\microtypesetup{activate=false}% +ISO copyright office\\ +CP 401 • Ch. de Blandonnet 8\\ +CH-1214 Vernier, Geneva, Switzerland\\ +Phone: + 41 22 749 01 11\\ +Email: copyright@iso.org\\ +Website: \url{www.iso.org}\\ +\end{indented} + +Published in Switzerland +\end{minipage}} + +\newpage +++++ +endif::[] + +ifeval::["{backend}" == "html5"] + +[[coverident]] +[.text-right] +ISO/IEC JTC1 SC22 WG21 [.large]#**{docno}**# + +{isodocno} + +Date: {revdate} + +ISO/IEC DIS {disno} + +ISO/IEC JTC1 SC22 + +Secretariat: ANSI + +[[covertitle]] +[.title]#**{doctitleen}**# + +{doctitlefr} + +.WARNING +**** +This document is not an ISO International Standard. It is distributed for +review and comment. It is subject to change without notice and may not be +referred to as an International Standard. + +Recipients of this draft are invited to submit, with their comments, +notification of any relevant patent rights of which they are aware and to +provide supporting documentation. +**** + +Document reference number: {isodocno} + +Document type: {isodoctype} + +Document stage: {isodocstage} + +Document Language: E + +ifeval::["{doclicense}" == "on"] +{isocopyright_lic_on} +endif::[] +ifeval::["{doclicense}" == "off"] +{isocopyright_lic_off} +endif::[] + +<<< + +**** +© ISO/IEC {docyear} + +ifeval::["{doclicense}" == "on"] +Except where otherwise noted, content is licensed under a Creative Commons +Attribution 4.0 International license (CC BY 4.0). +endif::[] + +[.indented] +ISO copyright office + +CP 401 • Ch. de Blandonnet 8 + +CH-1214 Vernier, Geneva, Switzerland + +Phone: + 41 22 749 01 11 + +Email: copyright@iso.org + +Website: https://www.iso.org[www.iso.org] + +Published in Switzerland +**** + +endif::[] diff --git a/src/eco_cover_reg.tex b/src/eco_cover_reg.tex index b382ce4..c009752 100644 --- a/src/eco_cover_reg.tex +++ b/src/eco_cover_reg.tex @@ -1,4 +1,7 @@ -%!TEX root = std.tex +%!TEX root = ecosystem.tex + +% Generated file. Do not edit. + %%-------------------------------------------------- %% Title page @@ -70,7 +73,7 @@ % \textbf{COPYRIGHT PROTECTED DOCUMENT} % \end{center} % \vspace{2ex} -% +% \copyright\ ISO/IEC \relyear\\ \ifdefined\license @@ -91,4 +94,4 @@ Published in Switzerland \end{minipage}} -\newpage +\newpage \ No newline at end of file diff --git a/src/eco_cover_wd.adoc b/src/eco_cover_wd.adoc new file mode 100644 index 0000000..9e0ea21 --- /dev/null +++ b/src/eco_cover_wd.adoc @@ -0,0 +1,55 @@ +include::in_vars.adoc[] + +ifeval::["{backend}" == "latexcore"] +[subs=macros] +++++ +%%-------------------------------------------------- +%% Title page + + +\thispagestyle{empty} +\begingroup +\def\hd{ +\begin{tabular}{ll} + \textbf{ISO Document:} & {\larger{pass:n[{isodocno}]}} \\ + \textbf{Document Number:} & {\larger{pass:n[{docno}]}} \\ + \textbf{Date:} & {pass:n[{revdate}]} \\ + \textbf{Revises:} & {pass:n[{prevdocno}]} \\ + \textbf{Reply to:} & {pass:n[{author}]} \\ + & {pass:n[{email}]} +\end{tabular} +} +\newlength{\hdwidth} +\settowidth{\hdwidth}{\hd} +\hfill\begin{minipage}{\hdwidth}\hd\end{minipage} +\endgroup + +\vspace{2.5cm} +\begin{center} +\textbf{\Huge +Working Draft, \doctitleen} +\end{center} +\vfill +\textbf{Note: this is an early draft. It's known to be incomplet and + incorrekt, and it has lots of + b\kern-1.2pta\kern1ptd\hspace{1.5em}for\kern-3ptmat\kern0.6ptti\raise0.15ex\hbox{n}g.} +\newpage +++++ +endif::[] + +ifeval::["{backend}" == "html5"] + +[horizontal] +ISO Document: :: {isodocno} +Document Number: :: {docno} +Date: :: {revdate} +Revises: :: {prevdocno} +Reply-to: :: {author} {email} + +[[covertitle]] +[.text-center] +[.title]#**{doctitle}**# + +<<< + +endif::[] diff --git a/src/eco_cover_wd.tex b/src/eco_cover_wd.tex index 78af01a..b5eb90c 100644 --- a/src/eco_cover_wd.tex +++ b/src/eco_cover_wd.tex @@ -1,18 +1,25 @@ %!TEX root = ecosystem.tex + +% Generated file. Do not edit. + +% Copyright 2024 René Ferdinand Rivera Morell +% Creative Commons Attribution 4.0 International License (CC BY 4.0) + %%-------------------------------------------------- %% Title page \thispagestyle{empty} \begingroup -\def\hd{\begin{tabular}{ll} - \textbf{ISO Document:} & {\larger\isodocno} \\ - \textbf{Document Number:} & {\larger\docno} \\ - \textbf{Date:} & \reldate \\ - \textbf{Revises:} & \prevdocno \\ - \textbf{Reply to:} & ISO C++ Tooling Study Group \\ - & sg15@lists.isocpp.org - \end{tabular} +\def\hd{ +\begin{tabular}{ll} + \textbf{ISO Document:} & {\larger{ISO/IEC -----:2024(E)}} \\ + \textbf{Document Number:} & {\larger{D3342R1}} \\ + \textbf{Date:} & {2024-11-05} \\ + \textbf{Revises:} & {} \\ + \textbf{Reply to:} & {ISO C++ Tooling Study Group} \\ + & {sg15@lists.isocpp.org} +\end{tabular} } \newlength{\hdwidth} \settowidth{\hdwidth}{\hd} @@ -28,4 +35,4 @@ \textbf{Note: this is an early draft. It's known to be incomplet and incorrekt, and it has lots of b\kern-1.2pta\kern1ptd\hspace{1.5em}for\kern-3ptmat\kern0.6ptti\raise0.15ex\hbox{n}g.} -\newpage +\newpage \ No newline at end of file diff --git a/src/eco_defs.adoc b/src/eco_defs.adoc new file mode 100644 index 0000000..accfdc1 --- /dev/null +++ b/src/eco_defs.adoc @@ -0,0 +1,90 @@ +include::in_vars.adoc[] +[.text-justify] +[[intro.defs,([intro.defs])]] += Terms and definitions [.right]#<># + +(((definitions))) +For the purposes of this document, +the terms and definitions given in ISO/IEC 2382, +the terms and definitions given in ISO/IEC 14882:2020, +and the following apply. + +ISO and IEC maintain terminology databases for use in standardization +at the following addresses: + +* ISO Online browsing platform: available at https://www.iso.org/obp/ +* IEC Electropedia: available at https://www.electropedia.org/ + +Terms that are used only in a small portion of this document are defined where +they are used and italicized where they are defined. + +[%nonum] +(((application))) + +[[defns.application,([defns.application])]] +application:: +a computer program that performs some desired function. + +NOTE: From POSIX. + +[%nonum] +(((capability))) + +[[defns.capability,([defns.capability])]] +capability:: +an aspect of an overall specification that defines a subset of the entire +specification. + +[%nonum] +(((directory))) + +[[defns.directory,([defns.directory])]] +directory:: +a file that contains directory entries. + +NOTE: From POSIX. + +[%nonum] +(((directory entry))) + +[[defns.direntry,([defns.direntry])]] +directory entry:: +an object that associates a filename with a file. + +NOTE: From POSIX. + +[%nonum] +(((file))) + +[[defns.file,([defns.file])]] +file:: +an object that can be written to, or read from, or both. + +NOTE: From POSIX. + +[%nonum] +(((filename))) + +[[defns.filename,([defns.filename])]] +filename:: +a sequence of bytes used to name a file. + +NOTE: From POSIX. + +[%nonum] +(((parent directory))) + +[[defns.parentdir,([defns.parentdir])]] +parent directory:: +a directory containing a directory entry for the file under discussion. + +NOTE: From POSIX. + +[%nonum] +(((pathname))) + +[[defns.pathname,([defns.pathname])]] +pathname:: +a string that is used to identify a file. + +NOTE: From POSIX. diff --git a/src/eco_defs.tex b/src/eco_defs.tex index 28af5d7..d5f984b 100644 --- a/src/eco_defs.tex +++ b/src/eco_defs.tex @@ -1,9 +1,15 @@ %!TEX root = ecosystem.tex +% Generated file. Do not edit. + +% Copyright 2024 René Ferdinand Rivera Morell +% Creative Commons Attribution 4.0 International License (CC BY 4.0) + +% Terms and definitions \rSec0[intro.defs]{Terms and definitions} \pnum -\indextext{definitions|(}% +\index[generalindex]{definitions} For the purposes of this document, the terms and definitions given in ISO/IEC 2382, the terms and definitions given in ISO/IEC 14882:2020, @@ -12,72 +18,84 @@ \pnum ISO and IEC maintain terminology databases for use in standardization at the following addresses: + \begin{itemize} -\item ISO Online browsing platform: available at \url{https://www.iso.org/obp} + +\item ISO Online browsing platform: available at \url{https://www.iso.org/obp/} + \item IEC Electropedia: available at \url{https://www.electropedia.org/} + \end{itemize} \pnum Terms that are used only in a small portion of this document are defined where they are used and italicized where they are defined. -\indexdefn{application}% +\index[generalindex]{application} + + \definition{application}{defns.application} a computer program that performs some desired function. - -\begin{defnote} +\begin{note} From POSIX. -\end{defnote} +\end{note} + +\index[generalindex]{capability} + -\indexdefn{capability}% \definition{capability}{defns.capability} an aspect of an overall specification that defines a subset of the entire specification. +\index[generalindex]{directory} + -\indexdefn{directory}% \definition{directory}{defns.directory} a file that contains directory entries. - -\begin{defnote} +\begin{note} From POSIX. -\end{defnote} +\end{note} + +\index[generalindex]{directory entry} + -\indexdefn{directory entry}% \definition{directory entry}{defns.direntry} an object that associates a filename with a file. - -\begin{defnote} +\begin{note} From POSIX. -\end{defnote} +\end{note} + +\index[generalindex]{file} + -\indexdefn{file}% \definition{file}{defns.file} an object that can be written to, or read from, or both. - -\begin{defnote} +\begin{note} From POSIX. -\end{defnote} +\end{note} + +\index[generalindex]{filename} + -\indexdefn{filename}% \definition{filename}{defns.filename} a sequence of bytes used to name a file. - -\begin{defnote} +\begin{note} From POSIX. -\end{defnote} +\end{note} + +\index[generalindex]{parent directory} + -\indexdefn{parent directory}% \definition{parent directory}{defns.parentdir} a directory containing a directory entry for the file under discussion. - -\begin{defnote} +\begin{note} From POSIX. -\end{defnote} +\end{note} + +\index[generalindex]{pathname} + -\indexdefn{pathname}% \definition{pathname}{defns.pathname} a string that is used to identify a file. - -\begin{defnote} +\begin{note} From POSIX. -\end{defnote} +\end{note} diff --git a/src/eco_diag.adoc b/src/eco_diag.adoc new file mode 100644 index 0000000..ec902c2 --- /dev/null +++ b/src/eco_diag.adoc @@ -0,0 +1,12 @@ +include::in_vars.adoc[] +[.text-justify] +[[diag,([diag])]] += Diagnostics Output [.right]#<># +:copyright: Copyright {docyear} René Ferdinand Rivera Morell +:license: Creative Commons Attribution 4.0 International License (CC BY 4.0) + +[[diag.pre,([diag.pre])]] +== Preamble [.right]#<># + +This clause describes options, output, and formats that define formatted +reporting of application diagnostics messages. diff --git a/src/eco_diag.tex b/src/eco_diag.tex new file mode 100644 index 0000000..6b365ef --- /dev/null +++ b/src/eco_diag.tex @@ -0,0 +1,16 @@ +%!TEX root = ecosystem.tex + +% Generated file. Do not edit. + +% Copyright 2024 René Ferdinand Rivera Morell +% Creative Commons Attribution 4.0 International License (CC BY 4.0) + +% Diagnostics Output +\rSec0[diag]{Diagnostics Output} + +% Preamble +\rSec1[diag.pre]{Preamble} + +\pnum +This clause describes options, output, and formats that define formatted +reporting of application diagnostics messages. diff --git a/src/eco_front.tex b/src/eco_front.tex deleted file mode 100644 index a832427..0000000 --- a/src/eco_front.tex +++ /dev/null @@ -1,35 +0,0 @@ -%!TEX root = ecosystem.tex -\ifdefined\isofinal -\input{eco_cover_reg} -\else -\input{eco_cover_wd} -\fi - -%%-------------------------------------------------- -%% The table of contents -\markboth{\contentsname}{} - -%%-------------------------------------------------- -%% Make a bit more room for our long page numbers. -\makeatletter -\renewcommand\@pnumwidth{2.5em} -\makeatother - -% Disable indexing within the table of contents -\newcommand{\indexoff}[2][generalindex]{} -\let\oindex\index -\let\index\indexoff - -%% Include table of contents. Do not list "Contents" -%% within it (per ISO request) but do include a -%% bookmark for it in the PDF. -\phantomsection -\pdfbookmark{\contentsname}{toctarget} -\hypertarget{toctarget}{\tableofcontents*} - -% Restore indexing -\let\index\oindex - -\setcounter{tocdepth}{5} - -\input{eco_preface} diff --git a/src/eco_introspection.adoc b/src/eco_introspection.adoc new file mode 100644 index 0000000..3882844 --- /dev/null +++ b/src/eco_introspection.adoc @@ -0,0 +1,385 @@ +include::in_vars.adoc[] +[.text-justify] +[[intspct,([intspct])]] += Introspection [.right]#<># +:copyright: Copyright {docyear} René Ferdinand Rivera Morell +:license: Creative Commons Attribution 4.0 International License (CC BY 4.0) + +[[intspct.pre,([intspct.pre])]] +== Preamble [.right]#<># + +This clause describes options, output, and formats that describe what +capabilities of this standard an application supports. An application shall +support the _minimum level_ functionality <>. An +application can support the _full level_ functionality <>. + +This clause specifies the ``std.info`` capability <>. + +[[intspct.overview,([intspct.overview])]] +== Overview [.right]#<># + +[subs="normal"] +.... +_application_ +[+ [.grammarterm]##std-info-opt## +[+ [.grammarterm]#declaration# +]+ +]+ +[+ [.grammarterm]#std-info-out-opt# _file_ +]+ +.... + +[[intspct.options,([intspct.options])]] +== Options [.right]#<># + +Applications shall accept one of two options syntax variations: +``--name=value`` (``--name`` without a value) or +``-name:value`` (``-name`` without a value). + +Applications shall indicate an error if invoked with an option syntax variation +that it does not support. + +NOTE: An application will report the error in what is conventional for the + platform it runs in. On POSIX and Windows it would return an error code, + and optionally output to the error stream. + +NOTE: It is up to a program that interacts with an application implementing + introspection to determine what option syntax variation the application + supports. One method to accomplish that is to execute the application with + one of the two syntax styles and use the error indication to conclude which + syntax works. Another is to have a priori knowledge of which syntax + variation works. + +[[intspct.opt.info,([intspct.opt.info])]] +=== Information Option [.right]#<># + +This option shall be supported. + +[.grammarterm]##std-info-opt## + +[.indented] +-- +Outputs the version information of the capabilities supported by the +application. +The option is specified as `--std-info` or `-std-info`. +The option can be specified zero or one time. +The application shall support the option for _minimum level_ +<> functionality. +-- + +[[intspct.opt.out,([intspct.opt.out])]] +=== Information Output Option [.right]#<># + +This option shall be supported. + +[.grammarterm]##std-info-out-opt## _file_ + +[.indented] +-- +The pathname of a file to output the information to. +The option is specified as ``--std-info-out=file`` or +``-std-info-out:file``. +If _file_ is ‘`-`’, the standard output shall be used. +The application shall support the option for _minimum level_ +<> functionality. +Not specifying this option while specifying the +[.grammarterm]##std-info-opt## option <> shall be +equivalent to also specifying a [.grammarterm]##std-info-out-opt## +[.grammarterm]##file## option where _file_ is ‘`-`’. +-- + +[[intspct.opt.decl,([intspct.opt.decl])]] +=== Declaration Option [.right]#<># + +This option should be supported. + +[.grammarterm]##std-info-opt## _declaration_ +[.indented] +-- +Declares the required capability version of the application. +The option is specified as ``--std-info=``_declaration_ or +``-std-info:``_declaration_. +The option can be specified any number of times. +The application shall support the option for _full level_ +<> functionality. +-- + +[[intspct.output,([intspct.output])]] +== Output [.right]#<># + +An application shall output a valid JSON text file that conforms to the +introspection schema <> to the file specified +in the options <>. + +[[intspct.file,([intspct.file])]] +== Files [.right]#<># + +An application can provide an _introspection file_ that contains valid +JSON that conforms to the introspection schema +<>. + +An _introspection file_ shall contain the same information as that produced +from the [.grammarterm]##std-info-opt## information option +<>. + +An _introspection file_ shall be named the same as the application with +any filename extension replaced with the ``stdinfo`` filename extension. It +is implementation defined how the filename of the introspection file replaces +the application filename extension with the new ``stdinfo`` filename +extension. + +NOTE: For Windows, POSIX, and other platforms replacing the filename extension + would remove any filename bytes after the last period + ([.ucode]#002E# [.uname]#FULL STOP#) and append the ``stdinfo`` sequence of + bytes. + +An _introspection file_ shall either have the same parent directory as +the application, have an implementation defined parent directory that is +relative to the parent directory of the application, or have an implementation +defined parent directory. + +[[intspct.schema,([intspct.schema])]] +== Schema [.right]#<># + +An introspection JSON text file shall contain one introspection JSON object +<>. + +[[intspct.schema.obj,([intspct.schema.obj])]] +=== Introspection Object [.right]#<># + +The _introspection object_ is the root JSON object of the introspection +JSON text. + +An _introspection object_ can have the following fields. + +[[intspct.schema.schema,([intspct.schema.schema])]] +=== JSON Schema Field [.right]#<># + +[.itemdescr] +[.fldname]#_Name_:# ``$schema`` + +[.fldtype]#_Type_:# `string` + +[.fldval]#_Value_:# + The value shall be a reference to a JSON Schema specification. + +[.flddesc]#_Description_:# + An _introspection object_ can contain this field. + If an _introspection object_ does not contain this field the value + shall be a reference to the JSON Schema corresponding to the current + edition of this standard. + +[[intspct.schema.cap,([intspct.schema.cap])]] +=== Capability Field [.right]#<># + +[.itemdescr] +[.fldname]#_Name_:# + [.grammarterm]##capability-identifier## <> + +[.fldtype]#_Type_:# + ``string`` or ``array`` + +[.fldval]#_Value_:# (for ``string``) + The value shall be a [.grammarterm]##version-number## for _minimum level_ + functionality. + Or the value shall be a [.grammarterm]##version-range## for _full level_ + functionality. + +[.fldval]#_Value_:# (for ``array``) + The value can be a JSON ``array`` for _full level_ functionality. + If the value is a JSON ``array`` the items in the ``array`` shall be a + [.grammarterm]##version-number## or [.grammarterm]##version-range##. + +[.flddesc]#_Description_:# + An _introspection object_ can contain this field one or more times. + When the field appears more than one time the name of the fields shall be + unique within the _introspection object_. + +[[intspct.cap,([intspct.cap])]] +== Capabilities [.right]#<># + +[.bnf] +capability-identifier:: + name scope-designator name [.opt]#sub-capability-identifier# +sub-capability-identifier:: + scope-designator name [.opt]#sub-capability-identifier# +name:: + [.descr]#one or more of:# + + [.ucode]#0061# .. [.ucode]#007A# [.uname]#LATIN SMALL LETTER A .. Z# + + [.ucode]#005F# [.uname]#LOW LINE# +scope-designator:: + [.ucode]#002E# [.uname]#FULL STOP# + +A [.grammarterm]##capability-identifier## is composed of two or more +[.grammarterm]##scope-designator## delimited [.grammarterm]##name## parts. + +The [.grammarterm]##name## ``std`` in a [.grammarterm]##capability-identifier## is +reserved for capabilities defined in this standard. + +Applications can specify vendor designated [.grammarterm]##name## parts defined +outside of this standard. + +[[intspct.vers,([intspct.vers])]] +== Versions [.right]#<># + +A version shall be either a single version number <> or a +version range <>. + +A single version number shall be equivalent to the inclusive version range +spanning solely that single version number. + +NOTE: That is, the version number ``i.j.k`` is equivalent to version range +``[i.j.k,i.j.k]``. + +[[intspct.vers.num,([intspct.vers.num])]] +=== Version Number [.right]#<># + +A version number shall conform to the SemVer ```` syntax. + +A version number can be truncated to only ```` or +``.`` syntax. + +A version number composed of only ```` is equivalent to +``.0.0``. + +A version number composed of only ``.`` is equivalent to +``..0``. + +Version numbers define a total ordering where version number _a_ is +ordered before a version number _b_ when _a_ has a lower SemVer +precedence than _b_. + +[[intspct.vers.range,([intspct.vers.range])]] +=== Version Range [.right]#<># + +[.bnf] +version-range:: + version-range-min-bracket + + version-min-number [.opt]#version-range-max-part# + + version-range-max-bracket +version-range-max-part:: + [.ucode]#002C# [.uname]#COMMA# version-max-number +version-min-number:: + version-number +version-max-number:: + version-number +version-range-min-bracket:: + [.descr]#one of:# + [.ucode]#005B# [.uname]#LEFT SQUARE BRACKET# + [.ucode]#0028# [.uname]#LEFT PARENTHESIS# +version-range-max-bracket:: + [.descr]#one of:# + [.ucode]#005D# [.uname]#RIGHT SQUARE BRACKET# + [.ucode]#0029# [.uname]#RIGHT PARENTHESIS# + +A version range is composed of either one version number bracketed, +or two version numbers separated by a [.ucode]#002C# [.uname]#COMMA# and bracketed. + +[example] +A version range with a single version number "```[1.0.0]```". + +[example] +A version range with a two version numbers "```[1.0.0,2.0.0]```". + +A version range _a_ that is ``[``_i_``,``_j_``]`` makes +_i_ and _j_ inclusive version range numbers, defining a Mathematics +closed interval. + +A version range _a_ that is ``(``_i_``,``_j_``)`` makes +_i_ and _j_ exclusive version range numbers, defining a Mathematics +open interval. + +A version range _a_ that is ``(``_i_``,``_j_``]`` makes +_i_ an exclusive version number and _j_ an inclusive version number, +defining a Mathematics half-open interval. + +A version range _a_ that is ``[``_i_``,``_j_``)`` makes +_j_ an exclusive version number. + +A version range with a single inclusive version number _x_ is equivalent +to the version range ``[``_x_``,``_x_``]``. + +A version range with a single exclusive version number _x_ is invalid. + +An exclusive version number _x_ does not include the version number +_x_ when compared to another version number _y_. + +A version range _a_ with version numbers _i_ and _j_ when +compared to a version range _b_ with version number _m_ and _n_ +will result in an empty version range when: _j_ < _m_ or +_n_ < _i_. + +Otherwise if _i_ or _m_ are inclusive version numbers and if _j_ +or _n_ are inclusive version numbers the resulting range when _a_ is +compare to _b_ is the inclusive version numbers "`lesser of _i_ and +_m_`" and "`lesser of _j_ and _n_`". + +Otherwise if _i_ or _m_ are inclusive version numbers and if _j_ +or _n_ are inclusive version numbers the resulting range when _a_ is +compare to _b_ is the inclusive version number "`lesser of _i_ and +_m_`" and the exclusive version number "`lesser of _j_ and _n_`". + +Otherwise if _j_ or _n_ are inclusive version numbers the resulting +range when _a_ is compared to _b_ is the exclusive version number +"`lesser of _i_ and _m_`" and the inclusive version number "`lesser of +_j_ and _n_`". + +Otherwise the resulting range when _a_ is compared to _b_ is the +exclusive version numbers "`lesser of _i_ and _m_`" and "`lesser of +_j_ and _n_`". + +[[intspct.min,([intspct.min])]] +== Minimum Level [.right]#<># + +An application that supports the _minimum level_ functionality indicates +it by specifying a single version <> as the value of the +``std.info`` capability <>. + +[example] +``{ "std.info": "1.0.0" }`` + +[[intspct.full,([intspct.full])]] +== Full Level [.right]#<># + +An application can support the _full level_ functionality as defined in +this section. An application that reports supporting the _full level_ +functionality shall support all of the functionality in this section. + +An application that supports the _full level_ functionality indicates it by +specifying a version range <> or an array of version +range items as the value of the ``std.info`` capability <>. + +[example] +``{ "std.info": "[1.0.0]" }`` + +An application that responds with an array of version range items as the value +of a capability field shall support the union of the range items indicated. + +[[intspct.info,([intspct.info])]] +== Introspection Information [.right]#<># + +An application shall output an introspection schema <> that +contains one capability field for each capability that the application supports +when given the ``--std-info`` option <>. + +An application shall indicate the single version <> or +version range <> of each capability it supports as the +value of the capability field. + +[[intspct.dcl,([intspct.dcl])]] +== Introspection Declaration [.right]#<># + +An application that supports the _full level_ functionality when given one +or more [.grammarterm]##std-info-opt## [.grammarterm]##declaration## options shall +conform its functionality to the indicated edition of this standard in the given +[.grammarterm]##declaration## [.grammarterm]##version-number## for the given capability. + +[.bnf] +declaration:: + capability-identifier [.ucode]#003d# [.uname]#equals sign# version-number + +An application, when not given a [.grammarterm]##std-info-opt## +[.grammarterm]##declaration## option for a capability it supports, should conform +its functionality to the most recent version of the standard it supports for +that capability. + +An application, when given a capability declaration option and the given +version is outside of the version range that the application supports, should +indicate an error. + +[[intspct.compat,([intspct.compat])]] +== Compatability [.right]#<># + + +An application shall indicate, per SemVer specification, that version _n_ +of the interface it implements is _backward compatible_ with another +version _p_ of the interface that another application implements when the +```` number is the same in version _n_ and _p_ and version +_n_ follows version _p_. diff --git a/src/eco_introspection.tex b/src/eco_introspection.tex index 228ef69..3b6b584 100644 --- a/src/eco_introspection.tex +++ b/src/eco_introspection.tex @@ -1,29 +1,34 @@ %!TEX root = ecosystem.tex -% intspct +% Generated file. Do not edit. + +% Copyright 2024 René Ferdinand Rivera Morell +% Creative Commons Attribution 4.0 International License (CC BY 4.0) + +% Introspection \rSec0[intspct]{Introspection} -% intspct.pre +% Preamble \rSec1[intspct.pre]{Preamble} \pnum This clause describes options, output, and formats that describe what capabilities of this standard an application supports. An application shall -support the \emph{minimum level} functionality \iref{intspct.min}. An -application can support the \emph{full level} functionality \iref{intspct.full}. +support the \emph{minimum level} functionality (\ref{intspct.min}). An +application can support the \emph{full level} functionality (\ref{intspct.full}). \pnum -This clause specifies the \verb|std.info| capability \iref{intspct.cap}. +This clause specifies the \verb|std.info| capability (\ref{intspct.cap}). -% intspct.overview +% Overview \rSec1[intspct.overview]{Overview} \pnum -\begin{outputblock} -@\emph{application}@ [ @\grammarterm{std-info-opt}@ [@\grammarterm{declaration}@] ] [ @\grammarterm{std-info-out-opt}@ @\emph{file}@ ] -\end{outputblock} +\begin{lstlisting}{} +@\emph{application}@ [ @\grammarterm{std-info-opt}@ [ @\grammarterm{declaration}@ ] ] [ @\grammarterm{std-info-out-opt}@ @\emph{file}@ ] +\end{lstlisting} -% intspct.options +% Options \rSec1[intspct.options]{Options} \pnum @@ -36,13 +41,13 @@ that it does not support. \begin{note} - An application will report the error in what is conventional for the +An application will report the error in what is conventional for the platform it runs in. On POSIX and Windows it would return an error code, and optionally output to the error stream. \end{note} \begin{note} - It is up to a program that interacts with an application implementing +It is up to a program that interacts with an application implementing introspection to determine what option syntax variation the application supports. One method to accomplish that is to execute the application with one of the two syntax styles and use the error indication to conclude which @@ -50,7 +55,7 @@ variation works. \end{note} -% intspct.opt.info +% Information Option \rSec2[intspct.opt.info]{Information Option} \pnum @@ -58,83 +63,91 @@ \pnum \grammarterm{std-info-opt} + \begin{indented} - Outputs the version information of the capabilities supported by the - application. - The option is specified as \verb@--std-info@ or \verb@-std-info@. - The option can be specified zero or one time. - The application shall support the option for \emph{minimum level} - \iref{intspct.min} functionality. +\pnum +Outputs the version information of the capabilities supported by the +application. +The option is specified as \verb|--std-info| or \verb|-std-info|. +The option can be specified zero or one time. +The application shall support the option for \emph{minimum level} +(\ref{intspct.min}) functionality. \end{indented} -% intspct.opt.out +% Information Output Option \rSec2[intspct.opt.out]{Information Output Option} \pnum This option shall be supported. \pnum -\grammarterm{std-info-out-opt} \grammarterm{file} +\grammarterm{std-info-out-opt} \emph{file} + \begin{indented} - The pathname of a file to output the information to. - The option is specified as \verb@--std-info-out=file@ or - \verb@-std-info-out:file@. - If \emph{file} is ‘\verb@-@’, the standard output shall be used. - The application shall support the option for \emph{minimum level} - \iref{intspct.min} functionality. - Not specifying this option while specifying the - \grammarterm{std-info-opt} option \iref{intspct.opt.info} shall be - equivalent to also specifying a \grammarterm{std-info-out-opt} - \grammarterm{file} option where \emph{file} is ‘\verb@-@’. +\pnum +The pathname of a file to output the information to. +The option is specified as \verb|--std-info-out=file| or +\verb|-std-info-out:file|. +If \emph{file} is ‘\verb|-|’, the standard output shall be used. +The application shall support the option for \emph{minimum level} +(\ref{intspct.min}) functionality. +Not specifying this option while specifying the +\grammarterm{std-info-opt} option (\ref{intspct.opt.info}) shall be +equivalent to also specifying a \grammarterm{std-info-out-opt} +\grammarterm{file} option where \emph{file} is ‘\verb|-|’. \end{indented} -% intspct.opt.decl +% Declaration Option \rSec2[intspct.opt.decl]{Declaration Option} \pnum This option should be supported. \pnum -\grammarterm{std-info-opt} \grammarterm{declaration} +\grammarterm{std-info-opt} \emph{declaration} + \begin{indented} - Declares the required capability version of the application. - The option is specified as \verb@--std-info=@\emph{declaration} or - \verb@-std-info:@\emph{declaration}. - The option can be specified any number of times. - The application shall support the option for \emph{full level} - \iref{intspct.full} functionality. +\pnum +Declares the required capability version of the application. +The option is specified as \verb|--std-info=|\emph{declaration} or +\verb|-std-info:|\emph{declaration}. +The option can be specified any number of times. +The application shall support the option for \emph{full level} +(\ref{intspct.full}) functionality. \end{indented} -% intspct.output +% Output \rSec1[intspct.output]{Output} \pnum An application shall output a valid JSON text file that conforms to the -introspection schema \iref{intspct.schema} to the file specified in the options -\iref{intspct.opt.out}. +introspection schema (\ref{intspct.schema}) to the file specified +in the options (\ref{intspct.opt.out}). -% intspct.file +% Files \rSec1[intspct.file]{Files} \pnum An application can provide an \emph{introspection file} that contains valid -JSON that conforms to the introspection schema \iref{intspct.schema}. +JSON that conforms to the introspection schema +(\ref{intspct.schema}). \pnum An \emph{introspection file} shall contain the same information as that produced -from the \grammarterm{std-info-opt} information option \iref{intspct.opt.info}. +from the \grammarterm{std-info-opt} information option +(\ref{intspct.opt.info}). \pnum An \emph{introspection file} shall be named the same as the application with -any filename extension replaced with the \verb@stdinfo@ filename extension. It +any filename extension replaced with the \verb|stdinfo| filename extension. It is implementation defined how the filename of the introspection file replaces -the application filename extension with the new \verb@stdinfo@ filename +the application filename extension with the new \verb|stdinfo| filename extension. \begin{note} - For Windows, POSIX, and other platforms replacing the filename extension +For Windows, POSIX, and other platforms replacing the filename extension would remove any filename bytes after the last period - (\ucode{002E} \uname{FULL STOP}) and append the \verb@stdinfo@ sequence of + (\ucode{002E} \uname{FULL STOP}) and append the \verb|stdinfo| sequence of bytes. \end{note} @@ -144,14 +157,14 @@ relative to the parent directory of the application, or have an implementation defined parent directory. -% intspct.schema +% Schema \rSec1[intspct.schema]{Schema} \pnum An introspection JSON text file shall contain one introspection JSON object -\iref{intspct.schema.obj}. +(\ref{intspct.schema.obj}). -% intspct.schema.obj +% Introspection Object \rSec2[intspct.schema.obj]{Introspection Object} \pnum @@ -161,88 +174,74 @@ \pnum An \emph{introspection object} can have the following fields. -% intspct.schema.schema +% JSON Schema Field \rSec2[intspct.schema.schema]{JSON Schema Field} + \begin{itemdescr} - \pnum - \fldname - \verb|$schema| +\pnum \fldname \verb|$schema| - \pnum - \fldtype - \verb|string| +\pnum \fldtype \verb|string| - \pnum - \fldval +\pnum \fldval The value shall be a reference to a JSON Schema specification. - \pnum - \flddesc +\pnum \flddesc An \emph{introspection object} can contain this field. If an \emph{introspection object} does not contain this field the value shall be a reference to the JSON Schema corresponding to the current edition of this standard. - \end{itemdescr} -% intspct.schema.cap +% Capability Field \rSec2[intspct.schema.cap]{Capability Field} + \begin{itemdescr} - \pnum - \fldname - \grammarterm{capability-identifier} \iref{intspct.cap} +\pnum \fldname + \grammarterm{capability-identifier} (\ref{intspct.cap}) - \pnum - \fldtype +\pnum \fldtype \verb|string| or \verb|array| - \pnum - \fldval (for \verb|string|) +\pnum \fldval (for \verb|string|) The value shall be a \grammarterm{version-number} for \emph{minimum level} functionality. Or the value shall be a \grammarterm{version-range} for \emph{full level} functionality. - \pnum - \fldval (for \verb|array|) +\pnum \fldval (for \verb|array|) The value can be a JSON \verb|array| for \emph{full level} functionality. If the value is a JSON \verb|array| the items in the \verb|array| shall be a \grammarterm{version-number} or \grammarterm{version-range}. - - \pnum - \flddesc + +\pnum \flddesc An \emph{introspection object} can contain this field one or more times. When the field appears more than one time the name of the fields shall be unique within the \emph{introspection object}. - \end{itemdescr} -% intspct.cap +% Capabilities \rSec1[intspct.cap]{Capabilities} -\pnum -\begin{ncbnf} +\begin{bnf} \nontermdef{capability-identifier}\br - name scope-designator name \opt{sub-capability-identifier} +name scope-designator name \opt{sub-capability-identifier} \nontermdef{sub-capability-identifier}\br - scope-designator name \opt{sub-capability-identifier} +scope-designator name \opt{sub-capability-identifier} \nontermdef{name}\br - \descr{one or more of:}\br - \ucode{0061} .. \ucode{007A} \uname{LATIN SMALL LETTER A .. Z}\br - \ucode{005F} \uname{LOW LINE} +\descr{one or more of:}\br +\ucode{0061} .. \ucode{007A} \uname{LATIN SMALL LETTER A .. Z}\br +\ucode{005F} \uname{LOW LINE} \nontermdef{scope-designator}\br - \ucode{002E} \uname{FULL STOP} - -\end{ncbnf} - +\ucode{002E} \uname{FULL STOP} +\end{bnf} \pnum A \grammarterm{capability-identifier} is composed of two or more \grammarterm{scope-designator} delimited \grammarterm{name} parts. @@ -255,12 +254,12 @@ Applications can specify vendor designated \grammarterm{name} parts defined outside of this standard. -% intspct.vers +% Versions \rSec1[intspct.vers]{Versions} \pnum -A version shall be either a single version number \iref{intspct.vers.num} or a -version range \iref{intspct.vers.range}. +A version shall be either a single version number (\ref{intspct.vers.num}) or a +version range (\ref{intspct.vers.range}). \pnum A single version number shall be equivalent to the inclusive version range @@ -271,7 +270,7 @@ \verb|[i.j.k,i.j.k]|. \end{note} -% intspct.vers.num +% Version Number \rSec2[intspct.vers.num]{Version Number} \pnum @@ -294,48 +293,45 @@ ordered before a version number \emph{b} when \emph{a} has a lower SemVer precedence than \emph{b}. -% intspct.vers.range +% Version Range \rSec2[intspct.vers.range]{Version Range} -\pnum -\begin{ncbnf} +\begin{bnf} \nontermdef{version-range}\br - version-range-min-bracket - version-min-number \opt{version-range-max-part} - version-range-max-bracket +version-range-min-bracket\br +version-min-number \opt{version-range-max-part}\br +version-range-max-bracket \nontermdef{version-range-max-part}\br - \ucode{002C} \uname{COMMA} version-max-number +\ucode{002C} \uname{COMMA} version-max-number \nontermdef{version-min-number}\br - version-number +version-number \nontermdef{version-max-number}\br - version-number +version-number \nontermdef{version-range-min-bracket}\br - \descr{one of:} - \ucode{005B} \uname{LEFT SQUARE BRACKET} - \ucode{0028} \uname{LEFT PARENTHESIS} +\descr{one of:}\br +\ucode{005B} \uname{LEFT SQUARE BRACKET}\br +\ucode{0028} \uname{LEFT PARENTHESIS} \nontermdef{version-range-max-bracket}\br - \descr{one of:} - \ucode{005D} \uname{RIGHT SQUARE BRACKET} - \ucode{0029} \uname{RIGHT PARENTHESIS} - -\end{ncbnf} - +\descr{one of:}\br +\ucode{005D} \uname{RIGHT SQUARE BRACKET}\br +\ucode{0029} \uname{RIGHT PARENTHESIS} +\end{bnf} \pnum A version range is composed of either one version number bracketed, or two version numbers separated by a \ucode{002C} \uname{COMMA} and bracketed. \begin{example} -A version range with a single version number "\verb|[1.0.0]|". +A version range with a single version number “\verb|[1.0.0]|”. \end{example} \begin{example} -A version range with a two version numbers "\verb|[1.0.0,2.0.0]|". +A version range with a two version numbers “\verb|[1.0.0,2.0.0]|”. \end{example} \pnum @@ -377,39 +373,39 @@ \pnum Otherwise if \emph{i} or \emph{m} are inclusive version numbers and if \emph{j} or \emph{n} are inclusive version numbers the resulting range when \emph{a} is -compare to \emph{b} is the inclusive version numbers "lesser of \emph{i} and -\emph{m}" and "lesser of \emph{j} and \emph{n}". +compare to \emph{b} is the inclusive version numbers “lesser of \emph{i} and +\emph{m}” and “lesser of \emph{j} and \emph{n}”. \pnum Otherwise if \emph{i} or \emph{m} are inclusive version numbers and if \emph{j} or \emph{n} are inclusive version numbers the resulting range when \emph{a} is -compare to \emph{b} is the inclusive version number "lesser of \emph{i} and -\emph{m}" and the exclusive version number "lesser of \emph{j} and \emph{n}". +compare to \emph{b} is the inclusive version number “lesser of \emph{i} and +\emph{m}” and the exclusive version number “lesser of \emph{j} and \emph{n}”. \pnum Otherwise if \emph{j} or \emph{n} are inclusive version numbers the resulting range when \emph{a} is compared to \emph{b} is the exclusive version number -"lesser of \emph{i} and \emph{m}" and the inclusive version number "lesser of -\emph{j} and \emph{n}". +“lesser of \emph{i} and \emph{m}” and the inclusive version number “lesser of +\emph{j} and \emph{n}”. \pnum Otherwise the resulting range when \emph{a} is compared to \emph{b} is the -exclusive version numbers "lesser of \emph{i} and \emph{m}" and "lesser of -\emph{j} and \emph{n}". +exclusive version numbers “lesser of \emph{i} and \emph{m}” and “lesser of +\emph{j} and \emph{n}”. -% intspct.min +% Minimum Level \rSec1[intspct.min]{Minimum Level} \pnum An application that supports the \emph{minimum level} functionality indicates -it by specifying a single version \iref{intspct.vers.num} as the value of the -\verb|std.info| capability \iref{intspct.cap}. +it by specifying a single version (\ref{intspct.vers.num}) as the value of the +\verb|std.info| capability (\ref{intspct.cap}). \begin{example} \verb|{ "std.info": "1.0.0" }| \end{example} -% intspct.full +% Full Level \rSec1[intspct.full]{Full Level} \pnum @@ -419,30 +415,31 @@ \pnum An application that supports the \emph{full level} functionality indicates it by -specifying a version range \iref{intspct.vers.range} or an array of version -range items as the value of the \verb|std.info| capability \iref{intspct.cap}. +specifying a version range (\ref{intspct.vers.range}) or an array of version +range items as the value of the \verb|std.info| capability (\ref{intspct.cap}). \begin{example} \verb|{ "std.info": "[1.0.0]" }| \end{example} +\pnum An application that responds with an array of version range items as the value of a capability field shall support the union of the range items indicated. -% intspct.info +% Introspection Information \rSec1[intspct.info]{Introspection Information} \pnum -An application shall output an introspection schema \iref{intspct.schema} that +An application shall output an introspection schema (\ref{intspct.schema}) that contains one capability field for each capability that the application supports -when given the \verb|--std-info| option \iref{intspct.opt.info}. +when given the \verb|--std-info| option (\ref{intspct.opt.info}). \pnum -An application shall indicate the single version \iref{intspct.vers.num} or -version range \iref{intspct.vers.range} of each capability it supports as the +An application shall indicate the single version (\ref{intspct.vers.num}) or +version range (\ref{intspct.vers.range}) of each capability it supports as the value of the capability field. -% intspct.dcl +% Introspection Declaration \rSec1[intspct.dcl]{Introspection Declaration} \pnum @@ -451,13 +448,11 @@ conform its functionality to the indicated edition of this standard in the given \grammarterm{declaration} \grammarterm{version-number} for the given capability. -\begin{ncbnf} +\begin{bnf} \nontermdef{declaration}\br - capability-identifier \ucode{003d} \uname{equals sign} version-number - -\end{ncbnf} - +capability-identifier \ucode{003d} \uname{equals sign} version-number +\end{bnf} \pnum An application, when not given a \grammarterm{std-info-opt} \grammarterm{declaration} option for a capability it supports, should conform @@ -469,11 +464,10 @@ version is outside of the version range that the application supports, should indicate an error. -% intspct.compat +% Compatability \rSec1[intspct.compat]{Compatability} \pnum - An application shall indicate, per SemVer specification, that version \emph{n} of the interface it implements is \emph{backward compatible} with another version \emph{p} of the interface that another application implements when the diff --git a/src/eco_introspection_annex.adoc b/src/eco_introspection_annex.adoc new file mode 100644 index 0000000..b8d3094 --- /dev/null +++ b/src/eco_introspection_annex.adoc @@ -0,0 +1,34 @@ +include::in_vars.adoc[] +[.ignore] +[[intsjschm.annex,([intsjschm.annex])]] += Annex A [.right]#<># +:copyright: Copyright {docyear} René Ferdinand Rivera Morell +:license: Creative Commons Attribution 4.0 International License (CC BY 4.0) + +:leveldedent: 1 + +[.infannex] +[.text-justify] +[[intsjschm,([intsjschm])]] +== Tool Introspection JSON Schema [.right]#<># + + +[[intsjschm.general,([intsjschm.general])]] +=== General [.right]#<># + +This Annex defines the introspection capability schema +<> in terms of a _JSON Schema_ +<>. + +This JSON Schema can be referenced as the `$schema` field with URI value +of `"std_info-1.0.0.json"`. + +[[intsjschm.spec,([intsjschm.spec])]] +=== JSON Schema Specification [.right]#<># + +[source,json] +---- +include::../pub/std_info-1.0.0.json[] +---- + +:leveldedent: 0 diff --git a/src/eco_introspection_annex.tex b/src/eco_introspection_annex.tex index ca1ae44..e9da6e0 100644 --- a/src/eco_introspection_annex.tex +++ b/src/eco_introspection_annex.tex @@ -1,27 +1,34 @@ %!TEX root = ecosystem.tex +% Generated file. Do not edit. + +% Copyright 2024 René Ferdinand Rivera Morell +% Creative Commons Attribution 4.0 International License (CC BY 4.0) + + +% Tool Introspection JSON Schema \infannex{intsjschm}{Tool Introspection JSON Schema} +% General \rSec1[intsjschm.general]{General} \pnum -This Annex defines the introspection capability schema \iref{intspct.schema} in -terms of a \emph{JSON Schema}. A \emph{JSON Schema} refers to the IETF RFC draft -"JSON Schema: A Media Type for Describing JSON Documents" as specified in -\url{https://json-schema.org/draft/2020-12/json-schema-core.html}. +This Annex defines the introspection capability schema +(\ref{intspct.schema}) in terms of a \emph{JSON Schema} +(\ref{jsonschema}). \pnum This JSON Schema can be referenced as the \verb|$schema| field with URI value -of \\ -\verb|"https://raw.githubusercontent.com/cplusplus/ecosystem-is/release/schema/std_info-1.0.0.json"|. +of \verb|"std_info-1.0.0.json"|. +% JSON Schema Specification \rSec1[intsjschm.spec]{JSON Schema Specification} -\begin{outputblock} + +\begin{lstlisting} { "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": - "https://raw.githubusercontent.com/cplusplus/ecosystem-is/release/schema/std_info-1.0.0.json", + "$id": "std_info-1.0.0.json", "title": "Tool Introspection Version 1.0.0 JSON Schema", "$defs": { "VersionMin": { @@ -71,8 +78,7 @@ "type": "object", "properties": { "$schema": { - "description": - "JSON Schema URI for the version of the tool introspection format.", + "description": "JSON Schema URI for the version of the tool introspection format.", "type": "string", "format": "uri" }, @@ -89,8 +95,6 @@ "additionalProperties": false } ], - "required": [ - "std.info" - ] + "required": ["std.info"] } -\end{outputblock} +\end{lstlisting} diff --git a/src/eco_license.adoc b/src/eco_license.adoc new file mode 100644 index 0000000..98d84be --- /dev/null +++ b/src/eco_license.adoc @@ -0,0 +1,381 @@ +include::in_vars.adoc[] +[.text-justify] +[[intro.license,([intro.license,intro.license])]] += License [.right]#<># +:copyright: Copyright {docyear}_René Ferdinand Rivera Morell +:license: Creative Commons Attribution 4.0 International License (CC BY 4.0) + +(((license))) +This work is licensed under the Creative Commons Attribution 4.0 International +License. To view a copy of this license, visit +https://creativecommons.org/licenses/by/4.0/ or send a letter to Creative +Commons, PO Box 1866, Mountain View, CA 94042, USA. + +[.text-justify] +[[intro.license.legalcode,([intro.license.legalcode])]] +== CC BY 4.0 [.right]#<># + +[.center] +-- +[%nonum] +*Creative Commons Attribution 4.0 International Public License* +-- + +[%nonum] +By exercising the Licensed Rights (defined below), You accept and agree +to be bound by the terms and conditions of this Creative Commons +Attribution 4.0 International Public License ("Public License"). To the +extent this Public License may be interpreted as a contract, You are +granted the Licensed Rights in consideration of Your acceptance of +these terms and conditions, and the Licensor grants You such rights in +consideration of benefits the Licensor receives from making the +Licensed Material available under these terms and conditions. + +[%nonum] +*Section 1 +--+ Definitions.* + +[loweralpha] +a. *Adapted Material* + means material subject to Copyright and Similar + Rights that is derived from or based upon the Licensed Material + and in which the Licensed Material is translated, altered, + arranged, transformed, or otherwise modified in a manner requiring + permission under the Copyright and Similar Rights held by the + Licensor. For purposes of this Public License, where the Licensed + Material is a musical work, performance, or sound recording, + Adapted Material is always produced where the Licensed Material is + synched in timed relation with a moving image. + +b. *Adapter's License* + means the license You apply to Your Copyright + and Similar Rights in Your contributions to Adapted Material in + accordance with the terms and conditions of this Public License. + +c. *Copyright and Similar Rights* + means copyright and/or similar rights + closely related to copyright including, without limitation, + performance, broadcast, sound recording, and Sui Generis Database + Rights, without regard to how the rights are labeled or + categorized. For purposes of this Public License, the rights + specified in Section 2(b)(1)-(2) are not Copyright and Similar + Rights. + +d. *Effective Technological Measures* + means those measures that, in the + absence of proper authority, may not be circumvented under laws + fulfilling obligations under Article 11 of the WIPO Copyright + Treaty adopted on December 20, 1996, and/or similar international + agreements. + +e. *Exceptions and Limitations* + means fair use, fair dealing, and/or + any other exception or limitation to Copyright and Similar Rights + that applies to Your use of the Licensed Material. + +f. *Licensed Material* means the artistic or literary work, database, + or other material to which the Licensor applied this Public + License. + +g. *Licensed Rights* + means the rights granted to You subject to the + terms and conditions of this Public License, which are limited to + all Copyright and Similar Rights that apply to Your use of the + Licensed Material and that the Licensor has authority to license. + +h. *Licensor* + means the individual(s) or entity(ies) granting rights + under this Public License. + +i. *Share* + means to provide material to the public by any means or + process that requires permission under the Licensed Rights, such + as reproduction, public display, public performance, distribution, + dissemination, communication, or importation, and to make material + available to the public including in ways that members of the + public may access the material from a place and at a time + individually chosen by them. + +j. *Sui Generis Database Rights* + means rights other than copyright + resulting from Directive 96/9/EC of the European Parliament and of + the Council of 11 March 1996 on the legal protection of databases, + as amended and/or succeeded, as well as other essentially + equivalent rights anywhere in the world. + +k. *You* + means the individual or entity exercising the Licensed Rights + under this Public License. Your has a corresponding meaning. + +[%nonum] +*Section 2 +--+ Scope* + +[loweralpha] +a. *License grant.* ++ +-- +[arabic] +1. Subject to the terms and conditions of this Public License, + the Licensor hereby grants You a worldwide, royalty-free, + non-sublicensable, non-exclusive, irrevocable license to + exercise the Licensed Rights in the Licensed Material to: ++ +[upperalpha] +A. reproduce and Share the Licensed Material, in whole or + in part; and +B. produce, reproduce, and Share Adapted Material. + +2. [.underline]#Exceptions and Limitations#. For the avoidance of + doubt, where Exceptions and Limitations apply to Your use, this Public + License does not apply, and You do not need to comply with + its terms and conditions. + +3. [.underline]#Term#. The term of this Public License is specified + in Section 6(a). + +4. [.underline]#Media and formats; technical modifications allowed#. + The Licensor authorizes You to exercise the Licensed Rights in + all media and formats whether now known or hereafter created, + and to make technical modifications necessary to do so. The + Licensor waives and/or agrees not to assert any right or + authority to forbid You from making technical modifications + necessary to exercise the Licensed Rights, including + technical modifications necessary to circumvent Effective + Technological Measures. For purposes of this Public License, + simply making modifications authorized by this Section 2(a) + (4) never produces Adapted Material. + +5. [.underline]#Downstream recipients#. ++ +[loweralpha] +a. [.underline]#Offer from the Licensor +--+ Licensed Material#. + Every recipient of the Licensed Material automatically + receives an offer from the Licensor to exercise the + Licensed Rights under the terms and conditions of this + Public License. +b. [.underline]#No downstream restrictions#. You may not offer + or impose any additional or different terms or conditions on, or + apply any Effective Technological Measures to, the + Licensed Material if doing so restricts exercise of the + Licensed Rights by any recipient of the Licensed + Material. +6. [.underline]#No endorsement#. Nothing in this Public License + constitutes or may be construed as permission to assert or imply that + You are, or that Your use of the Licensed Material is, connected + with, or sponsored, endorsed, or granted official status by, + the Licensor or others designated to receive attribution as + provided in Section 3(a)(1)(A)(i). +-- + +b. *Other rights.* ++ +-- +[arabic] +1. Moral rights, such as the right of integrity, are not + licensed under this Public License, nor are publicity, + privacy, and/or other similar personality rights; however, to + the extent possible, the Licensor waives and/or agrees not to + assert any such rights held by the Licensor to the limited + extent necessary to allow You to exercise the Licensed + Rights, but not otherwise. + +2. Patent and trademark rights are not licensed under this + Public License. + +3. To the extent possible, the Licensor waives any right to + collect royalties from You for the exercise of the Licensed + Rights, whether directly or through a collecting society + under any voluntary or waivable statutory or compulsory + licensing scheme. In all other cases the Licensor expressly + reserves any right to collect such royalties. +-- + +[%nonum] +*Section 3 +--+ License Conditions.* + +[%nonum] +Your exercise of the Licensed Rights is expressly made subject to the +following conditions. + +[loweralpha] +a. *Attribution*. ++ +-- +[arabic] +1. If You Share the Licensed Material (including in modified + form), You must: ++ +[upperalpha] +A. retain the following if it is supplied by the Licensor + with the Licensed Material: ++ +[lowerroman] +a. identification of the creator(s) of the Licensed + Material and any others designated to receive + attribution, in any reasonable manner requested by + the Licensor (including by pseudonym if + designated); +b. a copyright notice; +c. a notice that refers to this Public License; +d. a notice that refers to the disclaimer of warranties; +e. a URI or hyperlink to the Licensed Material to the + extent reasonably practicable; ++ +B. indicate if You modified the Licensed Material and + retain an indication of any previous modifications; and ++ +C. indicate the Licensed Material is licensed under this + Public License, and include the text of, or the URI or + hyperlink to, this Public License. + +2. You may satisfy the conditions in Section 3(a)(1) in any + reasonable manner based on the medium, means, and context in + which You Share the Licensed Material. For example, it may be + reasonable to satisfy the conditions by providing a URI or + hyperlink to a resource that includes the required + information. + +3. If requested by the Licensor, You must remove any of the + information required by Section 3(a)(1)(A) to the extent + reasonably practicable. + +4. If You Share Adapted Material You produce, the Adapter's + License You apply must not prevent recipients of the Adapted + Material from complying with this Public License. +-- + +[%nonum] +*Section 4 +--+ Sui Generis Database Rights.* + +[%nonum] +Where the Licensed Rights include Sui Generis Database Rights that +apply to Your use of the Licensed Material: + +[loweralpha] +a. for the avoidance of doubt, Section 2(a)(1) grants You the right + to extract, reuse, reproduce, and Share all or a substantial + portion of the contents of the database; + +b. if You include all or a substantial portion of the database + contents in a database in which You have Sui Generis Database + Rights, then the database in which You have Sui Generis Database + Rights (but not its individual contents) is Adapted Material; and + +c. You must comply with the conditions in Section 3(a) if You Share + all or a substantial portion of the contents of the database. + +[%nonum] +For the avoidance of doubt, this Section 4 supplements and does not +replace Your obligations under this Public License where the Licensed +Rights include other Copyright and Similar Rights. + +[%nonum] +*Section 5 +--+ Disclaimer of Warranties and Limitation of Liability.* + +[loweralpha] +a. UNLESS OTHERWISE SEPARATELY UNDERTAKEN BY THE LICENSOR, TO THE + EXTENT POSSIBLE, THE LICENSOR OFFERS THE LICENSED MATERIAL AS-IS + AND AS-AVAILABLE, AND MAKES NO REPRESENTATIONS OR WARRANTIES OF + ANY KIND CONCERNING THE LICENSED MATERIAL, WHETHER EXPRESS, + IMPLIED, STATUTORY, OR OTHER. THIS INCLUDES, WITHOUT LIMITATION, + WARRANTIES OF TITLE, MERCHANTABILITY, FITNESS FOR A PARTICULAR + PURPOSE, NON-INFRINGEMENT, ABSENCE OF LATENT OR OTHER DEFECTS, + ACCURACY, OR THE PRESENCE OR ABSENCE OF ERRORS, WHETHER OR NOT + KNOWN OR DISCOVERABLE. WHERE DISCLAIMERS OF WARRANTIES ARE NOT + ALLOWED IN FULL OR IN PART, THIS DISCLAIMER MAY NOT APPLY TO YOU. + +b. TO THE EXTENT POSSIBLE, IN NO EVENT WILL THE LICENSOR BE LIABLE + TO YOU ON ANY LEGAL THEORY (INCLUDING, WITHOUT LIMITATION, + NEGLIGENCE) OR OTHERWISE FOR ANY DIRECT, SPECIAL, INDIRECT, + INCIDENTAL, CONSEQUENTIAL, PUNITIVE, EXEMPLARY, OR OTHER LOSSES, + COSTS, EXPENSES, OR DAMAGES ARISING OUT OF THIS PUBLIC LICENSE OR + USE OF THE LICENSED MATERIAL, EVEN IF THE LICENSOR HAS BEEN + ADVISED OF THE POSSIBILITY OF SUCH LOSSES, COSTS, EXPENSES, OR + DAMAGES. WHERE A LIMITATION OF LIABILITY IS NOT ALLOWED IN FULL OR + IN PART, THIS LIMITATION MAY NOT APPLY TO YOU. + +c. The disclaimer of warranties and limitation of liability provided + above shall be interpreted in a manner that, to the extent + possible, most closely approximates an absolute disclaimer and + waiver of all liability. + +[%nonum] +*Section 6 +--+ Term and Termination.* + +[loweralpha] +a. This Public License applies for the term of the Copyright and + Similar Rights licensed here. However, if You fail to comply with + this Public License, then Your rights under this Public License + terminate automatically. + +b. Where Your right to use the Licensed Material has terminated under + Section 6(a), it reinstates: ++ +-- +[arabic] +1. automatically as of the date the violation is cured, provided + it is cured within 30 days of Your discovery of the + violation; or + +2. upon express reinstatement by the Licensor. +-- ++ +[%nonum] +For the avoidance of doubt, this Section 6(b) does not affect any +right the Licensor may have to seek remedies for Your violations +of this Public License. + +c. For the avoidance of doubt, the Licensor may also offer the + Licensed Material under separate terms or conditions or stop + distributing the Licensed Material at any time; however, doing so + will not terminate this Public License. + +d. Sections 1, 5, 6, 7, and 8 survive termination of this Public + License. + +[%nonum] +*Section 7 +--+ Other Terms and Conditions.* + +[loweralpha] +a. The Licensor shall not be bound by any additional or different + terms or conditions communicated by You unless expressly agreed. + +b. Any arrangements, understandings, or agreements regarding the + Licensed Material not stated herein are separate from and + independent of the terms and conditions of this Public License. + +[%nonum] +*Section 8 +--+ Interpretation.* + +[loweralpha] +a. For the avoidance of doubt, this Public License does not, and + shall not be interpreted to, reduce, limit, restrict, or impose + conditions on any use of the Licensed Material that could lawfully + be made without permission under this Public License. + +b. To the extent possible, if any provision of this Public License is + deemed unenforceable, it shall be automatically reformed to the + minimum extent necessary to make it enforceable. If the provision + cannot be reformed, it shall be severed from this Public License + without affecting the enforceability of the remaining terms and + conditions. + +c. No term or condition of this Public License will be waived and no + failure to comply consented to unless expressly agreed to by the + Licensor. + +d. Nothing in this Public License constitutes or may be interpreted + as a limitation upon, or waiver of, any privileges and immunities + that apply to the Licensor or You, including from the legal + processes of any jurisdiction or authority. + +[.text-justify] +[[intro.license.attribution,([intro.license.attribution])]] +== Attribution [.right]#<># + +[%nonum] +This document contains works copyrighted by the following entities or +individuals: + +* International Organization for Standardization, ISO +* International Electrotechnical Commission, IEC +* René Ferdinand Rivera Morell diff --git a/src/eco_license.tex b/src/eco_license.tex index 0dc622f..247be02 100644 --- a/src/eco_license.tex +++ b/src/eco_license.tex @@ -1,16 +1,21 @@ %!TEX root = ecosystem.tex -\rSec0[intro.license]{License} +% Generated file. Do not edit. + +% Copyright 2024_René Ferdinand Rivera Morell +% Creative Commons Attribution 4.0 International License (CC BY 4.0) -\indextext{license|(}% +% License +\rSec0[intro.license]{License} +\pnum +\index[generalindex]{license} This work is licensed under the Creative Commons Attribution 4.0 International License. To view a copy of this license, visit -\url{http://creativecommons.org/licenses/by/4.0/} or send a letter to Creative +\url{https://creativecommons.org/licenses/by/4.0/} or send a letter to Creative Commons, PO Box 1866, Mountain View, CA 94042, USA. -\indextext{license|)} - +% CC BY 4.0 \rSec1[intro.license.legalcode]{CC BY 4.0} \begin{center} @@ -26,269 +31,256 @@ consideration of benefits the Licensor receives from making the Licensed Material available under these terms and conditions. - \textbf{Section 1 -- Definitions.} -\begin{enumerate} - - \item[a.] - \textbf{Adapted Material} means material subject to Copyright and Similar - Rights that is derived from or based upon the Licensed Material - and in which the Licensed Material is translated, altered, - arranged, transformed, or otherwise modified in a manner requiring - permission under the Copyright and Similar Rights held by the - Licensor. For purposes of this Public License, where the Licensed - Material is a musical work, performance, or sound recording, - Adapted Material is always produced where the Licensed Material is - synched in timed relation with a moving image. - - \item[b.] - \textbf{Adapter's License} means the license You apply to Your Copyright - and Similar Rights in Your contributions to Adapted Material in - accordance with the terms and conditions of this Public License. - - \item[c.] - \textbf{Copyright and Similar Rights} means copyright and/or similar rights - closely related to copyright including, without limitation, - performance, broadcast, sound recording, and Sui Generis Database - Rights, without regard to how the rights are labeled or - categorized. For purposes of this Public License, the rights - specified in Section 2(b)(1)-(2) are not Copyright and Similar - Rights. - - \item[d.] - \textbf{Effective Technological Measures} means those measures that, in the - absence of proper authority, may not be circumvented under laws - fulfilling obligations under Article 11 of the WIPO Copyright - Treaty adopted on December 20, 1996, and/or similar international - agreements. - - \item[e.] - \textbf{Exceptions and Limitations} means fair use, fair dealing, and/or - any other exception or limitation to Copyright and Similar Rights - that applies to Your use of the Licensed Material. - - \item[f.] - \textbf{Licensed Material} means the artistic or literary work, database, - or other material to which the Licensor applied this Public - License. - - \item[g.] - \textbf{Licensed Rights} means the rights granted to You subject to the - terms and conditions of this Public License, which are limited to - all Copyright and Similar Rights that apply to Your use of the - Licensed Material and that the Licensor has authority to license. - - \item[h.] - \textbf{Licensor} means the individual(s) or entity(ies) granting rights - under this Public License. - - \item[i.] - \textbf{Share} means to provide material to the public by any means or - process that requires permission under the Licensed Rights, such - as reproduction, public display, public performance, distribution, - dissemination, communication, or importation, and to make material - available to the public including in ways that members of the - public may access the material from a place and at a time - individually chosen by them. - - \item[j.] - \textbf{Sui Generis Database Rights} means rights other than copyright - resulting from Directive 96/9/EC of the European Parliament and of - the Council of 11 March 1996 on the legal protection of databases, - as amended and/or succeeded, as well as other essentially - equivalent rights anywhere in the world. - - \item[k.] - \textbf{You} means the individual or entity exercising the Licensed Rights - under this Public License. Your has a corresponding meaning. +\begin{enumerate}[label=\alph*.] + +\item \textbf{Adapted Material} +means material subject to Copyright and Similar +Rights that is derived from or based upon the Licensed Material +and in which the Licensed Material is translated, altered, +arranged, transformed, or otherwise modified in a manner requiring +permission under the Copyright and Similar Rights held by the +Licensor. For purposes of this Public License, where the Licensed +Material is a musical work, performance, or sound recording, +Adapted Material is always produced where the Licensed Material is +synched in timed relation with a moving image. + +\item \textbf{Adapter’s License} +means the license You apply to Your Copyright +and Similar Rights in Your contributions to Adapted Material in +accordance with the terms and conditions of this Public License. + +\item \textbf{Copyright and Similar Rights} +means copyright and/or similar rights +closely related to copyright including, without limitation, +performance, broadcast, sound recording, and Sui Generis Database +Rights, without regard to how the rights are labeled or +categorized. For purposes of this Public License, the rights +specified in Section 2(b)(1)-(2) are not Copyright and Similar +Rights. + +\item \textbf{Effective Technological Measures} +means those measures that, in the +absence of proper authority, may not be circumvented under laws +fulfilling obligations under Article 11 of the WIPO Copyright +Treaty adopted on December 20, 1996, and/or similar international +agreements. + +\item \textbf{Exceptions and Limitations} +means fair use, fair dealing, and/or +any other exception or limitation to Copyright and Similar Rights +that applies to Your use of the Licensed Material. + +\item \textbf{Licensed Material} means the artistic or literary work, database, +or other material to which the Licensor applied this Public +License. + +\item \textbf{Licensed Rights} +means the rights granted to You subject to the +terms and conditions of this Public License, which are limited to +all Copyright and Similar Rights that apply to Your use of the +Licensed Material and that the Licensor has authority to license. + +\item \textbf{Licensor} +means the individual(s) or entity(ies) granting rights +under this Public License. + +\item \textbf{Share} +means to provide material to the public by any means or +process that requires permission under the Licensed Rights, such +as reproduction, public display, public performance, distribution, +dissemination, communication, or importation, and to make material +available to the public including in ways that members of the +public may access the material from a place and at a time +individually chosen by them. + +\item \textbf{Sui Generis Database Rights} +means rights other than copyright +resulting from Directive 96/9/EC of the European Parliament and of +the Council of 11 March 1996 on the legal protection of databases, +as amended and/or succeeded, as well as other essentially +equivalent rights anywhere in the world. + +\item \textbf{You} +means the individual or entity exercising the Licensed Rights +under this Public License. Your has a corresponding meaning. \end{enumerate} +\textbf{Section 2 -- Scope} -\textbf{Section 2 -- Scope.} - -\begin{enumerate} - - \item[a.] \textbf{License grant.} - - \begin{enumerate} - - \item[1.] Subject to the terms and conditions of this Public License, - the Licensor hereby grants You a worldwide, royalty-free, - non-sublicensable, non-exclusive, irrevocable license to - exercise the Licensed Rights in the Licensed Material to: - - \begin{enumerate} - - \item[a.] reproduce and Share the Licensed Material, in whole or - in part; and +\begin{enumerate}[label=\alph*.] - \item[b.] produce, reproduce, and Share Adapted Material. +\item \textbf{License grant.} - \end{enumerate} +\begin{enumerate}[label=\arabic*.] - \item[2.] \underline{Exceptions and Limitations}. For the avoidance of - doubt, where Exceptions and Limitations apply to Your use, this Public - License does not apply, and You do not need to comply with - its terms and conditions. +\item Subject to the terms and conditions of this Public License, +the Licensor hereby grants You a worldwide, royalty-free, +non-sublicensable, non-exclusive, irrevocable license to +exercise the Licensed Rights in the Licensed Material to: - \item[3.] \underline{Term}. The term of this Public License is specified - in Section 6(a). +\begin{enumerate}[label=\Alph*.] - \item[4.] \underline{Media and formats; technical modifications allowed}. - The Licensor authorizes You to exercise the Licensed Rights in - all media and formats whether now known or hereafter created, - and to make technical modifications necessary to do so. The - Licensor waives and/or agrees not to assert any right or - authority to forbid You from making technical modifications - necessary to exercise the Licensed Rights, including - technical modifications necessary to circumvent Effective - Technological Measures. For purposes of this Public License, - simply making modifications authorized by this Section 2(a) - (4) never produces Adapted Material. +\item reproduce and Share the Licensed Material, in whole or +in part; and - \item[5.] \underline{Downstream recipients}. - - \begin{enumerate} +\item produce, reproduce, and Share Adapted Material. - \item[a.] \underline{Offer from the Licensor -- Licensed Material}. - Every recipient of the Licensed Material automatically - receives an offer from the Licensor to exercise the - Licensed Rights under the terms and conditions of this - Public License. - - \item[b.] \underline{No downstream restrictions}. You may not offer - or impose any additional or different terms or conditions on, or - apply any Effective Technological Measures to, the - Licensed Material if doing so restricts exercise of the - Licensed Rights by any recipient of the Licensed - Material. - - \end{enumerate} - - \item[6.] \underline{No endorsement}. Nothing in this Public License - constitutes or may be construed as permission to assert or imply that - You are, or that Your use of the Licensed Material is, connected - with, or sponsored, endorsed, or granted official status by, - the Licensor or others designated to receive attribution as - provided in Section 3(a)(1)(A)(i). - - \end{enumerate} +\end{enumerate} +\item \underline{Exceptions and Limitations}. For the avoidance of +doubt, where Exceptions and Limitations apply to Your use, this Public +License does not apply, and You do not need to comply with +its terms and conditions. + +\item \underline{Term}. The term of this Public License is specified +in Section 6(a). + +\item \underline{Media and formats; technical modifications allowed}. +The Licensor authorizes You to exercise the Licensed Rights in +all media and formats whether now known or hereafter created, +and to make technical modifications necessary to do so. The +Licensor waives and/or agrees not to assert any right or +authority to forbid You from making technical modifications +necessary to exercise the Licensed Rights, including +technical modifications necessary to circumvent Effective +Technological Measures. For purposes of this Public License, +simply making modifications authorized by this Section 2(a) +(4) never produces Adapted Material. + +\item \underline{Downstream recipients}. + +\begin{enumerate}[label=\alph*.] + +\item \underline{Offer from the Licensor -- Licensed Material}. +Every recipient of the Licensed Material automatically +receives an offer from the Licensor to exercise the +Licensed Rights under the terms and conditions of this +Public License. + +\item \underline{No downstream restrictions}. You may not offer +or impose any additional or different terms or conditions on, or +apply any Effective Technological Measures to, the +Licensed Material if doing so restricts exercise of the +Licensed Rights by any recipient of the Licensed +Material. - \item[b.] \textbf{Other rights.} +\end{enumerate} +\item \underline{No endorsement}. Nothing in this Public License +constitutes or may be construed as permission to assert or imply that +You are, or that Your use of the Licensed Material is, connected +with, or sponsored, endorsed, or granted official status by, +the Licensor or others designated to receive attribution as +provided in Section 3(a)(1)(A)(i). - \begin{enumerate} +\end{enumerate} +\item \textbf{Other rights.} - \item[1.] Moral rights, such as the right of integrity, are not - licensed under this Public License, nor are publicity, - privacy, and/or other similar personality rights; however, to - the extent possible, the Licensor waives and/or agrees not to - assert any such rights held by the Licensor to the limited - extent necessary to allow You to exercise the Licensed - Rights, but not otherwise. +\begin{enumerate}[label=\arabic*.] - \item[2.] Patent and trademark rights are not licensed under this - Public License. +\item Moral rights, such as the right of integrity, are not +licensed under this Public License, nor are publicity, +privacy, and/or other similar personality rights; however, to +the extent possible, the Licensor waives and/or agrees not to +assert any such rights held by the Licensor to the limited +extent necessary to allow You to exercise the Licensed +Rights, but not otherwise. - \item[3.] To the extent possible, the Licensor waives any right to - collect royalties from You for the exercise of the Licensed - Rights, whether directly or through a collecting society - under any voluntary or waivable statutory or compulsory - licensing scheme. In all other cases the Licensor expressly - reserves any right to collect such royalties. +\item Patent and trademark rights are not licensed under this +Public License. - \end{enumerate} +\item To the extent possible, the Licensor waives any right to +collect royalties from You for the exercise of the Licensed +Rights, whether directly or through a collecting society +under any voluntary or waivable statutory or compulsory +licensing scheme. In all other cases the Licensor expressly +reserves any right to collect such royalties. \end{enumerate} - +\end{enumerate} \textbf{Section 3 -- License Conditions.} Your exercise of the Licensed Rights is expressly made subject to the following conditions. -\begin{enumerate} +\begin{enumerate}[label=\alph*.] - \item[a.] \textbf{Attribution}. +\item \textbf{Attribution}. - \begin{enumerate} +\begin{enumerate}[label=\arabic*.] - \item[1.] If You Share the Licensed Material (including in modified - form), You must: +\item If You Share the Licensed Material (including in modified +form), You must: - \begin{enumerate} +\begin{enumerate}[label=\Alph*.] - \item[a.] retain the following if it is supplied by the Licensor - with the Licensed Material: +\item retain the following if it is supplied by the Licensor +with the Licensed Material: - \begin{enumerate} +\begin{enumerate}[label=\roman*.] - \item[i.] identification of the creator(s) of the Licensed - Material and any others designated to receive - attribution, in any reasonable manner requested by - the Licensor (including by pseudonym if - designated); +\item identification of the creator(s) of the Licensed +Material and any others designated to receive +attribution, in any reasonable manner requested by +the Licensor (including by pseudonym if +designated); - \item[ii.] a copyright notice; +\item a copyright notice; - \item[iii.] a notice that refers to this Public License; +\item a notice that refers to this Public License; - \item[iv.] a notice that refers to the disclaimer of - warranties; +\item a notice that refers to the disclaimer of warranties; - \item[v.] a URI or hyperlink to the Licensed Material to the - extent reasonably practicable; +\item a URI or hyperlink to the Licensed Material to the +extent reasonably practicable; - \end{enumerate} - - \item[b.] indicate if You modified the Licensed Material and - retain an indication of any previous modifications; and - - \item[c.] indicate the Licensed Material is licensed under this - Public License, and include the text of, or the URI or - hyperlink to, this Public License. - - \end{enumerate} +\end{enumerate} +\item indicate if You modified the Licensed Material and +retain an indication of any previous modifications; and - \item[2.] You may satisfy the conditions in Section 3(a)(1) in any - reasonable manner based on the medium, means, and context in - which You Share the Licensed Material. For example, it may be - reasonable to satisfy the conditions by providing a URI or - hyperlink to a resource that includes the required - information. +\item indicate the Licensed Material is licensed under this +Public License, and include the text of, or the URI or +hyperlink to, this Public License. - \item[3.] If requested by the Licensor, You must remove any of the - information required by Section 3(a)(1)(A) to the extent - reasonably practicable. +\end{enumerate} +\item You may satisfy the conditions in Section 3(a)(1) in any +reasonable manner based on the medium, means, and context in +which You Share the Licensed Material. For example, it may be +reasonable to satisfy the conditions by providing a URI or +hyperlink to a resource that includes the required +information. - \item[4.] If You Share Adapted Material You produce, the Adapter's - License You apply must not prevent recipients of the Adapted - Material from complying with this Public License. +\item If requested by the Licensor, You must remove any of the +information required by Section 3(a)(1)(A) to the extent +reasonably practicable. - \end{enumerate} +\item If You Share Adapted Material You produce, the Adapter’s +License You apply must not prevent recipients of the Adapted +Material from complying with this Public License. \end{enumerate} - +\end{enumerate} \textbf{Section 4 -- Sui Generis Database Rights.} Where the Licensed Rights include Sui Generis Database Rights that apply to Your use of the Licensed Material: -\begin{enumerate} +\begin{enumerate}[label=\alph*.] - \item[a.] for the avoidance of doubt, Section 2(a)(1) grants You the right - to extract, reuse, reproduce, and Share all or a substantial - portion of the contents of the database; +\item for the avoidance of doubt, Section 2(a)(1) grants You the right +to extract, reuse, reproduce, and Share all or a substantial +portion of the contents of the database; - \item[b.] if You include all or a substantial portion of the database - contents in a database in which You have Sui Generis Database - Rights, then the database in which You have Sui Generis Database - Rights (but not its individual contents) is Adapted Material; and +\item if You include all or a substantial portion of the database +contents in a database in which You have Sui Generis Database +Rights, then the database in which You have Sui Generis Database +Rights (but not its individual contents) is Adapted Material; and - \item[c.] You must comply with the conditions in Section 3(a) if You Share - all or a substantial portion of the contents of the database. +\item You must comply with the conditions in Section 3(a) if You Share +all or a substantial portion of the contents of the database. \end{enumerate} @@ -296,126 +288,124 @@ replace Your obligations under this Public License where the Licensed Rights include other Copyright and Similar Rights. - \textbf{Section 5 -- Disclaimer of Warranties and Limitation of Liability.} -\begin{enumerate} - - \item[a.] UNLESS OTHERWISE SEPARATELY UNDERTAKEN BY THE LICENSOR, TO THE - EXTENT POSSIBLE, THE LICENSOR OFFERS THE LICENSED MATERIAL AS-IS - AND AS-AVAILABLE, AND MAKES NO REPRESENTATIONS OR WARRANTIES OF - ANY KIND CONCERNING THE LICENSED MATERIAL, WHETHER EXPRESS, - IMPLIED, STATUTORY, OR OTHER. THIS INCLUDES, WITHOUT LIMITATION, - WARRANTIES OF TITLE, MERCHANTABILITY, FITNESS FOR A PARTICULAR - PURPOSE, NON-INFRINGEMENT, ABSENCE OF LATENT OR OTHER DEFECTS, - ACCURACY, OR THE PRESENCE OR ABSENCE OF ERRORS, WHETHER OR NOT - KNOWN OR DISCOVERABLE. WHERE DISCLAIMERS OF WARRANTIES ARE NOT - ALLOWED IN FULL OR IN PART, THIS DISCLAIMER MAY NOT APPLY TO YOU. - - \item[b.] TO THE EXTENT POSSIBLE, IN NO EVENT WILL THE LICENSOR BE LIABLE - TO YOU ON ANY LEGAL THEORY (INCLUDING, WITHOUT LIMITATION, - NEGLIGENCE) OR OTHERWISE FOR ANY DIRECT, SPECIAL, INDIRECT, - INCIDENTAL, CONSEQUENTIAL, PUNITIVE, EXEMPLARY, OR OTHER LOSSES, - COSTS, EXPENSES, OR DAMAGES ARISING OUT OF THIS PUBLIC LICENSE OR - USE OF THE LICENSED MATERIAL, EVEN IF THE LICENSOR HAS BEEN - ADVISED OF THE POSSIBILITY OF SUCH LOSSES, COSTS, EXPENSES, OR - DAMAGES. WHERE A LIMITATION OF LIABILITY IS NOT ALLOWED IN FULL OR - IN PART, THIS LIMITATION MAY NOT APPLY TO YOU. - - \item[c.] The disclaimer of warranties and limitation of liability provided - above shall be interpreted in a manner that, to the extent - possible, most closely approximates an absolute disclaimer and - waiver of all liability. +\begin{enumerate}[label=\alph*.] + +\item UNLESS OTHERWISE SEPARATELY UNDERTAKEN BY THE LICENSOR, TO THE +EXTENT POSSIBLE, THE LICENSOR OFFERS THE LICENSED MATERIAL AS-IS +AND AS-AVAILABLE, AND MAKES NO REPRESENTATIONS OR WARRANTIES OF +ANY KIND CONCERNING THE LICENSED MATERIAL, WHETHER EXPRESS, +IMPLIED, STATUTORY, OR OTHER. THIS INCLUDES, WITHOUT LIMITATION, +WARRANTIES OF TITLE, MERCHANTABILITY, FITNESS FOR A PARTICULAR +PURPOSE, NON-INFRINGEMENT, ABSENCE OF LATENT OR OTHER DEFECTS, +ACCURACY, OR THE PRESENCE OR ABSENCE OF ERRORS, WHETHER OR NOT +KNOWN OR DISCOVERABLE. WHERE DISCLAIMERS OF WARRANTIES ARE NOT +ALLOWED IN FULL OR IN PART, THIS DISCLAIMER MAY NOT APPLY TO YOU. + +\item TO THE EXTENT POSSIBLE, IN NO EVENT WILL THE LICENSOR BE LIABLE +TO YOU ON ANY LEGAL THEORY (INCLUDING, WITHOUT LIMITATION, +NEGLIGENCE) OR OTHERWISE FOR ANY DIRECT, SPECIAL, INDIRECT, +INCIDENTAL, CONSEQUENTIAL, PUNITIVE, EXEMPLARY, OR OTHER LOSSES, +COSTS, EXPENSES, OR DAMAGES ARISING OUT OF THIS PUBLIC LICENSE OR +USE OF THE LICENSED MATERIAL, EVEN IF THE LICENSOR HAS BEEN +ADVISED OF THE POSSIBILITY OF SUCH LOSSES, COSTS, EXPENSES, OR +DAMAGES. WHERE A LIMITATION OF LIABILITY IS NOT ALLOWED IN FULL OR +IN PART, THIS LIMITATION MAY NOT APPLY TO YOU. + +\item The disclaimer of warranties and limitation of liability provided +above shall be interpreted in a manner that, to the extent +possible, most closely approximates an absolute disclaimer and +waiver of all liability. \end{enumerate} - \textbf{Section 6 -- Term and Termination.} -\begin{enumerate} - - \item[a.] This Public License applies for the term of the Copyright and - Similar Rights licensed here. However, if You fail to comply with - this Public License, then Your rights under this Public License - terminate automatically. +\begin{enumerate}[label=\alph*.] - \item[b.] Where Your right to use the Licensed Material has terminated under - Section 6(a), it reinstates: +\item This Public License applies for the term of the Copyright and +Similar Rights licensed here. However, if You fail to comply with +this Public License, then Your rights under this Public License +terminate automatically. - \begin{enumerate} +\item Where Your right to use the Licensed Material has terminated under +Section 6(a), it reinstates: - \item[1.] automatically as of the date the violation is cured, provided - it is cured within 30 days of Your discovery of the - violation; or +\begin{enumerate}[label=\arabic*.] - \item[2.] upon express reinstatement by the Licensor. +\item automatically as of the date the violation is cured, provided +it is cured within 30 days of Your discovery of the +violation; or - \end{enumerate} +\item upon express reinstatement by the Licensor. - For the avoidance of doubt, this Section 6(b) does not affect any - right the Licensor may have to seek remedies for Your violations - of this Public License. - - \item[c.] For the avoidance of doubt, the Licensor may also offer the - Licensed Material under separate terms or conditions or stop - distributing the Licensed Material at any time; however, doing so - will not terminate this Public License. +\end{enumerate} +For the avoidance of doubt, this Section 6(b) does not affect any +right the Licensor may have to seek remedies for Your violations +of this Public License. +\item For the avoidance of doubt, the Licensor may also offer the +Licensed Material under separate terms or conditions or stop +distributing the Licensed Material at any time; however, doing so +will not terminate this Public License. - \item[d.] Sections 1, 5, 6, 7, and 8 survive termination of this Public - License. +\item Sections 1, 5, 6, 7, and 8 survive termination of this Public +License. \end{enumerate} - \textbf{Section 7 -- Other Terms and Conditions.} -\begin{enumerate} +\begin{enumerate}[label=\alph*.] - \item[a.] The Licensor shall not be bound by any additional or different - terms or conditions communicated by You unless expressly agreed. +\item The Licensor shall not be bound by any additional or different +terms or conditions communicated by You unless expressly agreed. - \item[b.] Any arrangements, understandings, or agreements regarding the - Licensed Material not stated herein are separate from and - independent of the terms and conditions of this Public License. +\item Any arrangements, understandings, or agreements regarding the +Licensed Material not stated herein are separate from and +independent of the terms and conditions of this Public License. \end{enumerate} - \textbf{Section 8 -- Interpretation.} -\begin{enumerate} +\begin{enumerate}[label=\alph*.] - \item[a.] For the avoidance of doubt, this Public License does not, and - shall not be interpreted to, reduce, limit, restrict, or impose - conditions on any use of the Licensed Material that could lawfully - be made without permission under this Public License. +\item For the avoidance of doubt, this Public License does not, and +shall not be interpreted to, reduce, limit, restrict, or impose +conditions on any use of the Licensed Material that could lawfully +be made without permission under this Public License. - \item[b.] To the extent possible, if any provision of this Public License is - deemed unenforceable, it shall be automatically reformed to the - minimum extent necessary to make it enforceable. If the provision - cannot be reformed, it shall be severed from this Public License - without affecting the enforceability of the remaining terms and - conditions. +\item To the extent possible, if any provision of this Public License is +deemed unenforceable, it shall be automatically reformed to the +minimum extent necessary to make it enforceable. If the provision +cannot be reformed, it shall be severed from this Public License +without affecting the enforceability of the remaining terms and +conditions. - \item[c.] No term or condition of this Public License will be waived and no - failure to comply consented to unless expressly agreed to by the - Licensor. +\item No term or condition of this Public License will be waived and no +failure to comply consented to unless expressly agreed to by the +Licensor. - \item[d.] Nothing in this Public License constitutes or may be interpreted - as a limitation upon, or waiver of, any privileges and immunities - that apply to the Licensor or You, including from the legal - processes of any jurisdiction or authority. +\item Nothing in this Public License constitutes or may be interpreted +as a limitation upon, or waiver of, any privileges and immunities +that apply to the Licensor or You, including from the legal +processes of any jurisdiction or authority. \end{enumerate} - +% Attribution \rSec1[intro.license.attribution]{Attribution} This document contains works copyrighted by the following entities or individuals: \begin{itemize} - \item International Organization for Standardization, ISO - \item International Electrotechnical Commission, IEC - \item René Ferdinand Rivera Morell + +\item International Organization for Standardization, ISO + +\item International Electrotechnical Commission, IEC + +\item René Ferdinand Rivera Morell + \end{itemize} diff --git a/src/eco_preface.adoc b/src/eco_preface.adoc new file mode 100644 index 0000000..430852c --- /dev/null +++ b/src/eco_preface.adoc @@ -0,0 +1,54 @@ +include::in_vars.adoc[] +[.chapter] += Foreword + +[%nonum] +ISO (the International Organization for Standardization) is a worldwide +federation of national standards bodies (ISO member bodies). The work of +preparing International Standards is normally carried out through ISO technical +committees. Each member body interested in a subject for which a technical +committee has been established has the right to be represented on that +committee. International organizations, governmental and non-governmental, in +liaison with ISO, also take part in the work. ISO collaborates closely with the +International Electrotechnical Commission (IEC) on all matters of +electrotechnical standardization. + +[%nonum] +The procedures used to develop this document and those intended for its further +maintenance are described in the ISO/IEC Directives, Part 1. In particular, the +different approval criteria needed for the different types of ISO documents +should be noted. This document was drafted in accordance with the editorial +rules of the ISO/IEC Directives, Part 2 (see https://www.iso.org/directives). + +[%nonum] +Attention is drawn to the possibility that some of the elements of this document +may be the subject of patent rights. ISO shall not be held responsible for +identifying any or all such patent rights. Details of any patent rights +identified during the development of the document will be in the Introduction +and/or on the ISO list of patent declarations received +(see https://www.iso.org/patents). + +[%nonum] +Any trade name used in this document is information given for the convenience of +users and does not constitute an endorsement. + +[%nonum] +For an explanation of the voluntary nature of standards, the meaning of ISO +specific terms and expressions related to conformity assessment, as well as +information about ISO's adherence to the World Trade Organization (WTO) +principles in the Technical Barriers to Trade (TBT), +(see https://www.iso.org/iso/foreword.html). + +[%nonum] +This document was prepared by Technical Committee ISO/IEC JTC1, Information +technology, Subcommittee 22, Programming languages, their environments and +system software interfaces, Working Group 21, [.Cpp]#{CPP}#. + +[%nonum] +A list of all parts in the ISO/IEC [.disno]## ## series can be found on the ISO +website. + +[%nonum] +Any feedback or questions on this document should be directed to the user's +national standards body. A complete listing of these bodies can be found at +https://www.iso.org/members.html. diff --git a/src/eco_preface.tex b/src/eco_preface.tex index 761d34d..c1dd587 100644 --- a/src/eco_preface.tex +++ b/src/eco_preface.tex @@ -1,4 +1,10 @@ %!TEX root = ecosystem.tex + +% Generated file. Do not edit. + +% Copyright 2024 René Ferdinand Rivera Morell +% Creative Commons Attribution 4.0 International License (CC BY 4.0) + \chapter{Foreword} ISO (the International Organization for Standardization) is a worldwide @@ -15,33 +21,31 @@ \chapter{Foreword} maintenance are described in the ISO/IEC Directives, Part 1. In particular, the different approval criteria needed for the different types of ISO documents should be noted. This document was drafted in accordance with the editorial -rules of the ISO/IEC Directives, Part 2 (see \url{www.iso.org/directives}). +rules of the ISO/IEC Directives, Part 2 (see \url{https://www.iso.org/directives}). Attention is drawn to the possibility that some of the elements of this document may be the subject of patent rights. ISO shall not be held responsible for identifying any or all such patent rights. Details of any patent rights identified during the development of the document will be in the Introduction and/or on the ISO list of patent declarations received -(see \url{www.iso.org/patents}). +(see \url{https://www.iso.org/patents}). Any trade name used in this document is information given for the convenience of users and does not constitute an endorsement. For an explanation of the voluntary nature of standards, the meaning of ISO specific terms and expressions related to conformity assessment, as well as -information about ISO's adherence to the World Trade Organization (WTO) +information about ISO’s adherence to the World Trade Organization (WTO) principles in the Technical Barriers to Trade (TBT), -see www.iso.org/iso/foreword.html. +(see \url{https://www.iso.org/iso/foreword.html}). This document was prepared by Technical Committee ISO/IEC JTC1, Information technology, Subcommittee 22, Programming languages, their environments and -system software interfaces, Working Group 21, \Cpp. - -\input{eco_preface_changes.tex} +system software interfaces, Working Group 21, \Cpp{}. -A list of all parts in the ISO/IEC \disno\ series can be found on the ISO +A list of all parts in the ISO/IEC \disno{} series can be found on the ISO website. -Any feedback or questions on this document should be directed to the user's +Any feedback or questions on this document should be directed to the user’s national standards body. A complete listing of these bodies can be found at -\url{www.iso.org/members.html}. +\url{https://www.iso.org/members.html}. diff --git a/src/eco_preface_changes.adoc b/src/eco_preface_changes.adoc new file mode 100644 index 0000000..2cb4d25 --- /dev/null +++ b/src/eco_preface_changes.adoc @@ -0,0 +1,9 @@ +include::in_vars.adoc[] +:copyright: Copyright {docyear} René Ferdinand Rivera Morell +:license: Creative Commons Attribution 4.0 International License (CC BY 4.0) +:texbare: + +[%nonum] +The main changes are as follows: + +* Initial release. diff --git a/src/eco_preface_changes.tex b/src/eco_preface_changes.tex index c16841a..66e91eb 100644 --- a/src/eco_preface_changes.tex +++ b/src/eco_preface_changes.tex @@ -1,5 +1,14 @@ %!TEX root = ecosystem.tex +% Generated file. Do not edit. + +% Copyright 2024 René Ferdinand Rivera Morell +% Creative Commons Attribution 4.0 International License (CC BY 4.0) + The main changes are as follows: ---- Initial release. +\begin{itemize} + +\item Initial release. + +\end{itemize} diff --git a/src/eco_refs.adoc b/src/eco_refs.adoc new file mode 100644 index 0000000..99dc976 --- /dev/null +++ b/src/eco_refs.adoc @@ -0,0 +1,31 @@ +include::in_vars.adoc[] +[.text-justify] +[[intro.refs,([intro.refs])]] += Normative references [.right]#<># +:copyright: Copyright {docyear} René Ferdinand Rivera Morell +:license: Creative Commons Attribution 4.0 International License (CC BY 4.0) + +(((normative references,references,normative))) +The following documents are referred to in the text in such a way that some or +all of their content constitutes requirements of this document. For dated +references, only the edition cited applies. For undated references, the latest +edition of the referenced document (including any amendments) applies. + +// Groups, in order: +// . ISO documents in numerical order. +// . Other international standards. +// . Literature references. + +[%description] +Vocabulary:: + ISO/IEC 2382, _Information technology --- Vocabulary_ +POSIX:: + ISO/IEC 9945:2009, _Information technology --- Portable Operating System Interface (POSIX®) Base Specifications, Issue 7_ +{CPP}:: + ISO/IEC 14882:2020, _Programming languages --- {CPP}_ +JSON:: + ISO/IEC 21778:2017, _Information technology --- The JSON data interchange syntax_ +Mathematics:: + ISO 80000-2:2019, _Quantities and units --- Part 2: Mathematics_ +SemVer:: + The SemVer Team. _Semantic Versioning 2.0.0_. June 18 2013. Available at: https://semver.org/spec/v2.0.0.html diff --git a/src/eco_refs.tex b/src/eco_refs.tex index 6d423a2..22956e8 100644 --- a/src/eco_refs.tex +++ b/src/eco_refs.tex @@ -1,26 +1,25 @@ %!TEX root = ecosystem.tex -\rSec0[intro.refs]{Normative references}% -\indextext{normative references|see{references, normative}}% +% Generated file. Do not edit. + +% Copyright 2024 René Ferdinand Rivera Morell +% Creative Commons Attribution 4.0 International License (CC BY 4.0) + +% Normative references +\rSec0[intro.refs]{Normative references} \pnum -\indextext{references!normative|(}% +\index[generalindex]{normative references} The following documents are referred to in the text in such a way that some or all of their content constitutes requirements of this document. For dated references, only the edition cited applies. For undated references, the latest edition of the referenced document (including any amendments) applies. \begin{description} - -% ISO documents in numerical order. - -\item[Vocabulary] ISO/IEC 2382, \doccite{Information technology --- Vocabulary} -\item[POSIX] ISO/IEC 9945:2009, \doccite{Information technology --- Portable Operating System Interface (POSIX®) Base Specifications, Issue 7} -\item[C++] ISO/IEC 14882:2020, \doccite{Programming languages --- C++} -\item[JSON] ISO/IEC 21778:2017, \doccite{Information technology --- The JSON data interchange syntax} -\item[Mathematics] ISO 80000-2:2019, \doccite{Quantities and units --- Part 2: Mathematics} -\item[SemVer] The SemVer Team. \doccite{Semantic Versioning 2.0.0}. June 18 2013. Available at: \url{https://semver.org/spec/v2.0.0.html} - -% Other international standards. - -\end{description} +\item[Vocabulary] ISO/IEC 2382, \emph{Information technology --- Vocabulary} +\item[POSIX] ISO/IEC 9945:2009, \emph{Information technology --- Portable Operating System Interface (POSIX®) Base Specifications, Issue 7} +\item[C++] ISO/IEC 14882:2020, \emph{Programming languages --- C++} +\item[JSON] ISO/IEC 21778:2017, \emph{Information technology --- The JSON data interchange syntax} +\item[Mathematics] ISO 80000-2:2019, \emph{Quantities and units --- Part 2: Mathematics} +\item[SemVer] The SemVer Team. \emph{Semantic Versioning 2.0.0}. June 18 2013. Available at: \url{https://semver.org/spec/v2.0.0.html} +\end{description} \ No newline at end of file diff --git a/src/eco_scope.adoc b/src/eco_scope.adoc new file mode 100644 index 0000000..0eea8fb --- /dev/null +++ b/src/eco_scope.adoc @@ -0,0 +1,16 @@ +include::in_vars.adoc[] +[.text-justify] +[[intro.scope,([intro.scope])]] += Scope [.right]#<># +:copyright: Copyright {docyear} René Ferdinand Rivera Morell +:license: Creative Commons Attribution 4.0 International License (CC BY 4.0) + +(((scope))) +This document specifies formats, processes, definitions, and so on, that +facilitates the interoperation of the tools and systems that implement, and +interface with, the [.Cpp]#{CPP}# programming language. + +(((C++))) +[.Cpp]#{CPP}# is a general purpose programming language described in ISO/IEC 14882:2020 +[.doccite]#Programming languages --- {CPP}# (hereinafter referred to as the +{CPP} standard). diff --git a/src/eco_scope.tex b/src/eco_scope.tex index 507586c..3f934d6 100644 --- a/src/eco_scope.tex +++ b/src/eco_scope.tex @@ -1,15 +1,21 @@ %!TEX root = ecosystem.tex +% Generated file. Do not edit. + +% Copyright 2024 René Ferdinand Rivera Morell +% Creative Commons Attribution 4.0 International License (CC BY 4.0) + +% Scope \rSec0[intro.scope]{Scope} \pnum -\indextext{scope|(}% +\index[generalindex]{scope} This document specifies formats, processes, definitions, and so on, that facilitates the interoperation of the tools and systems that implement, and interface with, the \Cpp{} programming language. \pnum +\index[generalindex]{C++} \Cpp{} is a general purpose programming language described in ISO/IEC 14882:2020 \doccite{Programming languages --- C++} (hereinafter referred to as the -\defnx{C++ standard}{C++!standard}). -\indextext{scope|)} +C++ standard). diff --git a/src/eco_strctparam.adoc b/src/eco_strctparam.adoc new file mode 100644 index 0000000..e23b8e3 --- /dev/null +++ b/src/eco_strctparam.adoc @@ -0,0 +1,206 @@ +include::in_vars.adoc[] +[.text-justify] +[[strctparam,([strctparam])]] += Structured Parameters [.right]#<># +:copyright: Copyright {docyear} René Ferdinand Rivera Morell +:license: Creative Commons Attribution 4.0 International License (CC BY 4.0) + +[[strctparam.pre,([strctparam.pre])]] +== Preamble [.right]#<># + +This clause describes options, output, and formats that control the behavior of +applications through the specification of arguments and options from +_structured parameters_. + +This clause specifies the ``std.strctparam`` capabilit + <> version `1.0.0`. + +An application can implement this capability. + +An application that implements the `std.strctparam` capability shall +include the `std.strctparam` field and version value in the introspection +JSON text output <>. + +[.text-justify] +[[strctparam.overview,([strctparam.overview])]] +== Overview [.right]#<># + +[subs="normal"] +.... +_application_ +[+ _std-strctparam-input_ _file_ +]+ +.... + +[[strctparam.input,([strctparam.input])]] +== Input Option [.right]#<># + +[.grammarterm]##std-strctparam-input## + +[.indented] +-- +The pathname of a file to read the _structured parameters_ from. +The option is specified as `--std-param=`__file__ or `-std-param:`__file__. +If __file__ is '`-`', the standard input shall be used. +-- + +[[strctparam.file,([strctparam.file])]] +== Files [.right]#<># + +An application shall read a valid JSON text file that conforms to the +_structured parameters_ schema <>. + +An application shall interpret the information in the file as if the options +and arguments in the file occur in the same position as the +_std-strctparam-input_ parameter of the list of parameters given to +the application. Given either directly as part of the application command line +or as part of the arguments field <>. + +An application shall process arguments in the file in the order that they +appear. + +An application shall process options in the file as if the a new modified state +replaces the current state. + +[[strctparam.schema,([strctparam.schema])]] +== Schema [.right]#<># + +A _structured parameters_ JSON text file shall contain one _structured +parameters_ JSON object <>. + +[[strctparam.schema.obj,([strctparam.schema.obj])]] +=== Structured Parameters Object [.right]#<># + +The _structured parameters object_ is the root JSON object of the +structured parameters JSON text. + +A _structured parameters object_ can have the following fields. + +A _structured parameters object_ shall have only one of the +`arguments` and `options` fields. + +[[strctparam.schema.schema,([strctparam.schema.schema])]] +=== JSON Schema Field [.right]#<># + +[.itemdescr] +[.fldname]#_Name_:# `$schema` + +[.fldtype]#_Type_:# `string` + +[.fldval]#_Value_:# + The value shall be a reference to a JSON Schema specification. + +[.flddesc]#_Description_:# + A _structured parameters object_ can contain this field. + If a _structured parameters object_ does not contain this field the + value shall be a reference to the JSON Schema corresponding to the current + edition of this standard <>. + +[[strctparam.schema.ver,([strctparam.schema.ver])]] +=== Version Field [.right]#<># + +[.itemdescr] +[.fldname]#_Name_:# `version` + +[.fldtype]#_Type_:# `string` + +[.fldval]#_Value_:# `1` or `1.0` or `1.0.0` + +[.flddesc]#_Description_:# + The version field indicates the version of the _structured parameters_ + represented in the contents of the JSON text. + If a _structured parameters object_ does not contain this field the + value shall be '1.0.0'. + +[[strctparam.schema.args,([strctparam.schema.args])]] +=== Arguments Field [.right]#<># + +[.itemdescr] +[.fldname]#_Name_:# `arguments` + +[.fldtype]#_Type_:# `array` + +[.fldval]#_Value_:# + The value shall be a JSON `array`. The items in the `array` shall be of JSON + `string` types. + +[.flddesc]#_Description_:# + The arguments field specifies items to be interpreted directly as if they + occur in the command line of the program. + +The application shall process the items as if they replace the +`__std-strctparam-input__` argument. + +[[strctparam.schema.opts,([strctparam.schema.opts])]] +=== Options Field [.right]#<># + +[.itemdescr] +[.fldname]#_Name_:# `options` + +[.fldtype]#_Type_:# `object` + +[.fldval]#_Value_:# The value shall be a JSON `object`. + +[.flddesc]#_Description_:# + A _structured parameters object_ can contain this _structured + options_ field. The keys of items shall be _name_ + <> values. + +[[strctparam.schema.names,([strctparam.schema.names])]] +=== Names [.right]#<># + +[.bnf] +name:: + [.descr]#one or more of:# + + [.ucode]#0061# .. [.ucode]#007A# [.uname]#LATIN SMALL LETTER A .. Z# + + [.ucode]#0030# .. [.ucode]#0039# [.uname]#DIGIT ZERO .. NINE# + + [.ucode]#005F# [.uname]#LOW LINE# [.ucode]#002D# [.uname]#HYPHEN-MINUS# +scope:: + name scope-designator [.opt]#scope# +scope-designator:: + [.ucode]#002E# [.uname]#FULL STOP# + +The _name_ `std` is reserved for _structured options_ +defined in this standard. + +Applications can specify vendor designated _name_ parts outside of +this standard. + +[[strctparam.schema.opt.param,([strctparam.schema.opt.param])]] +=== Structured Option std.param [.right]#<># + +The `std.param` _structured option_ defines an option to refer to additional +_structured parameters_ <> to process. + +An application shall implement this option. + +The `std.param` option shall have the following fields. + +[.itemdescr] +[.fldname]#_Name_:# `pre` + +[.fldtype]#_Type_:# `string` or `array` + +[.fldval]#_Value_:# + (for `string`) A pathname to a file containing _structured parameters_ + <>. + +[.fldval]#_Value_:# + (for `array`) A list of pathname `string` items to files containing + _structured parameters_ <> + +[.flddesc]#_Description_:# + One or more references to files that include additional _structured + parameters_ <>. + +[.itemdescr] +[.fldname]#_Name_:# `post` + +[.fldtype]#_Type_:# `string` or `array` + +[.fldval]#_Value_:# + (for `string`) A pathname to a file containing _structured parameters_ + <>. + +[.fldval]#_Value_:# + (for `array`) A list of pathname `string` items to files containing + _structured parameters_ <> + +[.flddesc]#_Description_:# + One or more references to files that include additional _structured + parameters_ <>. + +A `string` value in the `pre` or `post` field shall be as if the +value was given as an `array` with the `string` value as the only +value in the `array`. + +An application shall process the _structured parameters_ <> in the +`pre` field before processing the _structured options_ where the +`std.param` option is specified. + +An application shall process the _structured parameters_ <> in the +`post` field after processing the _structured options_ where the +`std.param` option is specified. + +An application shall process the _structured parameters_ <> in the +`pre` and `post` field in the order given in the value applying +semantics as specified in the parameters or options of the _structured +parameters_. diff --git a/src/eco_strctparam.tex b/src/eco_strctparam.tex new file mode 100644 index 0000000..ab1ccec --- /dev/null +++ b/src/eco_strctparam.tex @@ -0,0 +1,272 @@ +%!TEX root = ecosystem.tex + +% Generated file. Do not edit. + +% Copyright 2024 René Ferdinand Rivera Morell +% Creative Commons Attribution 4.0 International License (CC BY 4.0) + +% Structured Parameters +\rSec0[strctparam]{Structured Parameters} + +% Preamble +\rSec1[strctparam.pre]{Preamble} + +\pnum +This clause describes options, output, and formats that control the behavior of +applications through the specification of arguments and options from +\emph{structured parameters}. + +\pnum +This clause specifies the \verb|std.strctparam| capabilit + (\ref{intspct.cap}) version \verb|1.0.0|. + +\pnum +An application can implement this capability. + +\pnum +An application that implements the \verb|std.strctparam| capability shall +include the \verb|std.strctparam| field and version value in the introspection +JSON text output (\ref{intspct.schema.cap}). + +% Overview +\rSec1[strctparam.overview]{Overview} + +\pnum +\begin{lstlisting}{} +@\emph{application}@ [ @\emph{std-strctparam-input}@ @\emph{file}@ ] +\end{lstlisting} + +% Input Option +\rSec1[strctparam.input]{Input Option} + +\pnum +\grammarterm{std-strctparam-input} + +\begin{indented} +\pnum +The pathname of a file to read the \emph{structured parameters} from. +The option is specified as `--std-param=`\emph{file} or `-std-param:`\emph{file}. +If \emph{file} is ‘-’, the standard input shall be used. +\end{indented} + +% Files +\rSec1[strctparam.file]{Files} + +\pnum +An application shall read a valid JSON text file that conforms to the +\emph{structured parameters} schema (\ref{strctparam.schema}). + +\pnum +An application shall interpret the information in the file as if the options +and arguments in the file occur in the same position as the +\emph{std-strctparam-input} parameter of the list of parameters given to +the application. Given either directly as part of the application command line +or as part of the arguments field (\ref{strctparam.schema.args}). + +\pnum +An application shall process arguments in the file in the order that they +appear. + +\pnum +An application shall process options in the file as if the a new modified state +replaces the current state. + +% Schema +\rSec1[strctparam.schema]{Schema} + +\pnum +A \emph{structured parameters} JSON text file shall contain one \emph{structured +parameters} JSON object (\ref{strctparam.schema.obj}). + +% Structured Parameters Object +\rSec2[strctparam.schema.obj]{Structured Parameters Object} + +\pnum +The \emph{structured parameters object} is the root JSON object of the +structured parameters JSON text. + +\pnum +A \emph{structured parameters object} can have the following fields. + +\pnum +A \emph{structured parameters object} shall have only one of the +\verb|arguments| and \verb|options| fields. + +% JSON Schema Field +\rSec2[strctparam.schema.schema]{JSON Schema Field} + + +\begin{itemdescr} + +\pnum \fldname \verb|$schema| + +\pnum \fldtype \verb|string| + +\pnum \fldval + The value shall be a reference to a JSON Schema specification. + +\pnum \flddesc + A \emph{structured parameters object} can contain this field. + If a \emph{structured parameters object} does not contain this field the + value shall be a reference to the JSON Schema corresponding to the current + edition of this standard (\ref{strctparamjschm}). +\end{itemdescr} + +% Version Field +\rSec2[strctparam.schema.ver]{Version Field} + + +\begin{itemdescr} + +\pnum \fldname \verb|version| + +\pnum \fldtype \verb|string| + +\pnum \fldval \verb|1| or \verb|1.0| or \verb|1.0.0| + +\pnum \flddesc + The version field indicates the version of the \emph{structured parameters} + represented in the contents of the JSON text. + If a \emph{structured parameters object} does not contain this field the + value shall be '1.0.0'. +\end{itemdescr} + +% Arguments Field +\rSec2[strctparam.schema.args]{Arguments Field} + + +\begin{itemdescr} + +\pnum \fldname \verb|arguments| + +\pnum \fldtype \verb|array| + +\pnum \fldval + The value shall be a JSON \verb|array|. The items in the \verb|array| shall be of JSON + \verb|string| types. + +\pnum \flddesc + The arguments field specifies items to be interpreted directly as if they + occur in the command line of the program. +\end{itemdescr} + +\pnum +The application shall process the items as if they replace the +\verb|\emph{std-strctparam-input}| argument. + +% Options Field +\rSec2[strctparam.schema.opts]{Options Field} + + +\begin{itemdescr} + +\pnum \fldname \verb|options| + +\pnum \fldtype \verb|object| + +\pnum \fldval The value shall be a JSON \verb|object|. + +\pnum \flddesc + A \emph{structured parameters object} can contain this \emph{structured + options} field. The keys of items shall be \emph{name} + (\ref{strctparam.schema.names}) values. +\end{itemdescr} + +% Names +\rSec2[strctparam.schema.names]{Names} + +\begin{bnf} + +\nontermdef{name}\br +\descr{one or more of:}\br +\ucode{0061} .. \ucode{007A} \uname{LATIN SMALL LETTER A .. Z}\br +\ucode{0030} .. \ucode{0039} \uname{DIGIT ZERO .. NINE}\br +\ucode{005F} \uname{LOW LINE} \ucode{002D} \uname{HYPHEN-MINUS} + +\nontermdef{scope}\br +name scope-designator \opt{scope} + +\nontermdef{scope-designator}\br +\ucode{002E} \uname{FULL STOP} +\end{bnf} +\pnum +The \emph{name} \verb|std| is reserved for \emph{structured options} +defined in this standard. + +\pnum +Applications can specify vendor designated \emph{name} parts outside of +this standard. + +% Structured Option std.param +\rSec2[strctparam.schema.opt.param]{Structured Option std.param} + +\pnum +The \verb|std.param| \emph{structured option} defines an option to refer to additional +\emph{structured parameters} (\ref{strctparam}) to process. + +\pnum +An application shall implement this option. + +\pnum +The \verb|std.param| option shall have the following fields. + + +\begin{itemdescr} + +\pnum \fldname \verb|pre| + +\pnum \fldtype \verb|string| or \verb|array| + +\pnum \fldval + (for \verb|string|) A pathname to a file containing \emph{structured parameters} + (\ref{strctparam}). + +\pnum \fldval + (for \verb|array|) A list of pathname \verb|string| items to files containing + \emph{structured parameters} (\ref{strctparam}) + +\pnum \flddesc + One or more references to files that include additional \emph{structured + parameters} (\ref{strctparam}). +\end{itemdescr} + + +\begin{itemdescr} + +\pnum \fldname \verb|post| + +\pnum \fldtype \verb|string| or \verb|array| + +\pnum \fldval + (for \verb|string|) A pathname to a file containing \emph{structured parameters} + (\ref{strctparam}). + +\pnum \fldval + (for \verb|array|) A list of pathname \verb|string| items to files containing + \emph{structured parameters} (\ref{strctparam}) + +\pnum \flddesc + One or more references to files that include additional \emph{structured + parameters} (\ref{strctparam}). +\end{itemdescr} + +\pnum +A \verb|string| value in the \verb|pre| or \verb|post| field shall be as if the +value was given as an \verb|array| with the \verb|string| value as the only +value in the \verb|array|. + +\pnum +An application shall process the \emph{structured parameters} (\ref{strctparam}) in the +\verb|pre| field before processing the \emph{structured options} where the +\verb|std.param| option is specified. + +\pnum +An application shall process the \emph{structured parameters} (\ref{strctparam}) in the +\verb|post| field after processing the \emph{structured options} where the +\verb|std.param| option is specified. + +\pnum +An application shall process the \emph{structured parameters} (\ref{strctparam}) in the +\verb|pre| and \verb|post| field in the order given in the value applying +semantics as specified in the parameters or options of the \emph{structured +parameters}. diff --git a/src/eco_strctparam_annex.adoc b/src/eco_strctparam_annex.adoc new file mode 100644 index 0000000..0523801 --- /dev/null +++ b/src/eco_strctparam_annex.adoc @@ -0,0 +1,34 @@ +include::in_vars.adoc[] +[.ignore] +[[strctparamjschm.annex,([strctparamjschm.annex])]] += Annex B [.right]#<># +:copyright: Copyright {docyear} René Ferdinand Rivera Morell +:license: Creative Commons Attribution 4.0 International License (CC BY 4.0) + +:leveldedent: 1 + +[.infannex] +[.text-justify] +[[strctparamjschm,([strctparamjschm])]] +== Structured Parameters JSON Schema [.right]#<># + + +[[strctparamjschm.general,([strctparamjschm.general])]] +=== General [.right]#<># + +This Annex defines the structured parameters capability schema +<> in terms of a _JSON Schema_ +<>. + +This JSON Schema can be referenced as the \verb|$schema| field with URI value +of `"std_param-1.0.0.json"`. + +[[strctparamjschm.spec,([strctparamjschm.spec])]] +=== JSON Schema Specification [.right]#<># + +[source,json] +---- +include::../pub/std_param-1.0.0.json[] +---- + +:leveldedent: 0 diff --git a/src/eco_strctparam_annex.tex b/src/eco_strctparam_annex.tex new file mode 100644 index 0000000..5d9cfc8 --- /dev/null +++ b/src/eco_strctparam_annex.tex @@ -0,0 +1,112 @@ +%!TEX root = ecosystem.tex + +% Generated file. Do not edit. + +% Copyright 2024 René Ferdinand Rivera Morell +% Creative Commons Attribution 4.0 International License (CC BY 4.0) + + +% Structured Parameters JSON Schema +\infannex{strctparamjschm}{Structured Parameters JSON Schema} + +% General +\rSec1[strctparamjschm.general]{General} + +\pnum +This Annex defines the structured parameters capability schema +(\ref{strctparam.schema}) in terms of a \emph{JSON Schema} +(\ref{jsonschema}). + +\pnum +This JSON Schema can be referenced as the \verb|$schema| field with URI value +of \verb|"std_param-1.0.0.json"|. + +% JSON Schema Specification +\rSec1[strctparamjschm.spec]{JSON Schema Specification} + + +\begin{lstlisting} +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "std_param-1.0.0.json", + "title": "Structured Parameters Version 1.0.0 JSON Schema", + "type": "object", + "properties": { + "$schema": { + "description": "JSON Schema URI for the version of the structured parameters format.", + "type": "string", + "format": "uri" + }, + "version": { + "description": "The Structured Parameters format version.", + "type": "string", + "$ref": "#/$defs/Version" + }, + "arguments": { + "description": "Application direct arguments.", + "type": "array", + "items": { + "type": "string" + } + }, + "options": { + "description": "Application structured options.", + "type": "object", + "allOf": [ + { + "$ref": "#/$opt/Std.Param" + } + ], + "propertyName": { + "$ref": "#/$defs/Name" + } + } + }, + "oneOf": [ + { + "required": ["arguments"] + }, + { + "required": ["options"] + } + ], + "$defs": { + "Version": { + "type": "string", + "pattern": "^[0-9]+([.][0-9]+){0,2}$" + }, + "Name": { + "type": "string", + "pattern": "^([a-z0-9_-]+[.])*([a-z0-9_-]+)$" + }, + "StringOrArray": { + "type": ["string", "array"], + "items": { + "type": "string" + } + } + }, + "$opt": { + "Std.Param": { + "properties": { + "std.param": { + "description": "Recursive reference to one or more structured parameters files.", + "type": "object", + "properties": { + "pre": { + "$ref": "#/$defs/StringOrArray" + }, + "post": { + "$ref": "#/$defs/StringOrArray" + } + }, + "additionalProperties": false + } + }, + "param": { + "$ref": "#/$opt/Std.Param/properties/std.param" + } + } + } +} +\end{lstlisting} diff --git a/src/eco_strctparam_core.adoc b/src/eco_strctparam_core.adoc new file mode 100644 index 0000000..295c8eb --- /dev/null +++ b/src/eco_strctparam_core.adoc @@ -0,0 +1,21 @@ +include::in_vars.adoc[] +[.text-justify] +[[strctparamcore,([strctparamcore])]] += Structured Parameters Core Options [.right]#<># +:copyright: Copyright {docyear} René Ferdinand Rivera Morell +:license: Creative Commons Attribution 4.0 International License (CC BY 4.0) + +[[strctparamcore.pre,([strctparamcore.pre])]] +== Preamble [.right]#<># + +This clause describes the schema and semantics of core _structured options_ +<> for {CPP} compiler front-ends. + +This clause specifies the `std.strctparam.core` capability +<> version `1.0.0`. + +An application can implement this capability. + +An application that implements the `std.strctparam.core` capability shall +include the `std.strctparam.core` field and version value in the +introspection JSON text output <>. diff --git a/src/eco_strctparam_core.tex b/src/eco_strctparam_core.tex new file mode 100644 index 0000000..d041509 --- /dev/null +++ b/src/eco_strctparam_core.tex @@ -0,0 +1,28 @@ +%!TEX root = ecosystem.tex + +% Generated file. Do not edit. + +% Copyright 2024 René Ferdinand Rivera Morell +% Creative Commons Attribution 4.0 International License (CC BY 4.0) + +% Structured Parameters Core Options +\rSec0[strctparamcore]{Structured Parameters Core Options} + +% Preamble +\rSec1[strctparamcore.pre]{Preamble} + +\pnum +This clause describes the schema and semantics of core \emph{structured options} +(\ref{strctparam.schema.opts}) for C++ compiler front-ends. + +\pnum +This clause specifies the \verb|std.strctparam.core| capability +(\ref{intspct.cap}) version \verb|1.0.0|. + +\pnum +An application can implement this capability. + +\pnum +An application that implements the \verb|std.strctparam.core| capability shall +include the \verb|std.strctparam.core| field and version value in the +introspection JSON text output (\ref{intspct.schema.cap}). diff --git a/src/ecosystem.adoc b/src/ecosystem.adoc new file mode 100644 index 0000000..a3ab696 --- /dev/null +++ b/src/ecosystem.adoc @@ -0,0 +1,87 @@ +include::in_vars.adoc[] += Standard for C++ Ecosystem +:version-label!: +:reproducible: +:nofooter: +:toc: macro +:toc-title: Contents +:toclevels: 5 +:caution-caption: Caution: +:important-caption: Important: +:note-caption: Note: +:tip-caption: Tip: +:warning-caption: Warning: +:source-highlighter: rouge +:texroot!: +:noheader: + +ifeval::["{backend}" == "html5"] +++++ + +++++ +endif::[] + +//------------------------------------------------------------------- +// Front matter.. +:sectnums!: + +ifeval::["{docstage}" == "draft"] +include::eco_cover_wd.adoc[leveloffset=+1] +endif::[] +ifeval::["{docstage}" == "final"] +include::eco_cover_reg.adoc[leveloffset=+1] +endif::[] + +ifeval::["{docstage}" == "web"] +[[covertitle]] +[.text-center] +[.title]#**{doctitle}**# + +[sidebar] +-- +[.text-center.small] +This is _not_ an ISO publication. + +Generated on {docdatetime} from Asciidoctor sources. +-- +endif::[] + +toc::[] + +ifeval::["{docstage}" != "web"] +include::eco_preface.adoc[leveloffset=+1] +include::eco_preface_changes.adoc[leveloffset=+1] +endif::[] + +ifeval::["{doclicense}" == "on"] +include::eco_license.adoc[leveloffset=+1] +endif::[] + +//------------------------------------------------------------------- +// Chapters.. +:sectnums: + +include::eco_scope.adoc[leveloffset=+1] +include::eco_refs.adoc[leveloffset=+1] +include::eco_conformance.adoc[leveloffset=+1] +include::eco_defs.adoc[leveloffset=+1] +include::eco_introspection.adoc[leveloffset=+1] +include::eco_strctparam.adoc[leveloffset=+1] +include::eco_strctparam_core.adoc[leveloffset=+1] +include::eco_diag.adoc[leveloffset=+1] + +//------------------------------------------------------------------- +// Appendices.. +:sectnums!: + +include::eco_introspection_annex.adoc[leveloffset=+1] +include::eco_strctparam_annex.adoc[leveloffset=+1] + +//------------------------------------------------------------------- +// Back matter.. +:sectnums!: + +include::eco_back_biblio.adoc[leveloffset=+1] +include::eco_back_xref.adoc[leveloffset=+1] +include::eco_back_index.adoc[leveloffset=+1] diff --git a/src/ecosystem.tex b/src/ecosystem.tex index 930709d..7e17935 100644 --- a/src/ecosystem.tex +++ b/src/ecosystem.tex @@ -59,6 +59,7 @@ \input{in_macros} \input{in_tables} +% Declare the general index (the only one we have) \makeindex[name=generalindex,title=Index,options=-s eco_generalindex.ist] \makeglossary[xrefindex] \makeglossary[xrefdelta] @@ -90,7 +91,35 @@ %%-------------------------------------------------- %% front matter \frontmatter -\input{eco_front} + +% Cover +\ifdefined\isofinal +\input{eco_cover_reg} +\else +\input{eco_cover_wd} +\fi + +% The table of contents +\markboth{\contentsname}{} +% Make a bit more room for ToC page numbers. +\makeatletter +\renewcommand\@pnumwidth{2.5em} +\makeatother +% Include table of contents. Do not list "Contents" +% within it (per ISO request) but do include a +% bookmark for it in the PDF. +\phantomsection +\pdfbookmark{\contentsname}{toctarget} +\hypertarget{toctarget}{\tableofcontents*} +% ToC levels? +\setcounter{tocdepth}{5} + +% Foreword +\input{eco_preface} +\input{eco_preface_changes.tex} +\ifdefined\license +\input{eco_license} +\fi %%-------------------------------------------------- %% main body of the document @@ -99,14 +128,14 @@ %%-------------------------------------------------- %% chapters -\ifdefined\license -\input{eco_license} -\fi \input{eco_scope} \input{eco_refs} \input{eco_conformance} \input{eco_defs} \input{eco_introspection} +\input{eco_strctparam} +\input{eco_strctparam_core} +\input{eco_diag} %%-------------------------------------------------- %% appendices @@ -119,11 +148,14 @@ % \makeatother \input{eco_introspection_annex} +\input{eco_strctparam_annex} %%-------------------------------------------------- %% back matter \backmatter -\input{eco_back} +\input{eco_back_biblio} +\input{eco_back_xref} +\input{eco_back_index} %%-------------------------------------------------- %% End of document diff --git a/src/in_config.adoc b/src/in_config.adoc new file mode 100644 index 0000000..4c542ae --- /dev/null +++ b/src/in_config.adoc @@ -0,0 +1,33 @@ +include::in_vars.adoc[] + +ifeval::["{backend}" == "latexcore"] +[subs=macros] +++++ +%%-------------------------------------------------- +%% Release date +\DTMsavenow{currentdate} +\newcommand{\reldate}{\today} +\newcommand{\relyear}{\DTMfetchyear{currentdate}} +\newcommand{\relmonth}{\DTMfetchmonth{currentdate}} + +%% Version numbers +\newcommand{\docno}{pass:a[{docno}]} +\newcommand{\disno}{pass:a[{disno}]} +\newcommand{\isodocno}{pass:a[{isodocno}]} +\newcommand{\prevdocno}{pass:a[{prevdocno}]} + +%% Title +\newcommand{\doctitleen}{pass:a[{doctitleen}]} +\newcommand{\doctitlefr}{pass:a[{doctitlefr}]} + +%% Common bits +\ifdefined\license +\newcommand{\isocopyright}{\copyright\ ISO/IEC pass:a[{docyear}] --- CC BY 4.0} +\else +\newcommand{\isocopyright}{\copyright\ ISO/IEC pass:a[{docyear}] --- All rights reserved} +\fi + +%% States +\newcommand{\isodoctype}{pass:a[{isodoctype}]} +\newcommand{\isodocstage}{pass:a[{isodocstage}]} +++++ diff --git a/src/in_config.tex b/src/in_config.tex index 4ae7d74..0b3da4b 100644 --- a/src/in_config.tex +++ b/src/in_config.tex @@ -1,4 +1,10 @@ %!TEX root = ecosystem.tex + +% Generated file. Do not edit. + +% Copyright 2024 René Ferdinand Rivera Morell +% Creative Commons Attribution 4.0 International License (CC BY 4.0) + %%-------------------------------------------------- %% Release date \DTMsavenow{currentdate} @@ -7,28 +13,22 @@ \newcommand{\relmonth}{\DTMfetchmonth{currentdate}} %% Version numbers -\newcommand{\docno}{Dxxxx} -\newcommand{\disno}{00000} -\newcommand{\isodocno}{ISO/IEC \disno:\relyear(E)} -\newcommand{\prevdocno}{Nnnnn} +\newcommand{\docno}{D3342R1} +\newcommand{\disno}{-----} +\newcommand{\isodocno}{ISO/IEC -----:2024(E)} +\newcommand{\prevdocno}{} %% Title -\newcommand{\doctitleen}{Standard for \Cpp{} Ecosystem} -\newcommand{\doctitlefr}{Norme pour L'écosystème \Cpp{}} +\newcommand{\doctitleen}{Standard for C++ Ecosystem} +\newcommand{\doctitlefr}{Norme pour L'écosystème C++} %% Common bits \ifdefined\license -\newcommand{\isocopyright}{\copyright\ ISO/IEC \relyear\ --- CC BY 4.0} +\newcommand{\isocopyright}{\copyright\ ISO/IEC 2024 --- CC BY 4.0} \else -\newcommand{\isocopyright}{\copyright\ ISO/IEC \relyear\ --- All rights reserved} +\newcommand{\isocopyright}{\copyright\ ISO/IEC 2024 --- All rights reserved} \fi %% States \newcommand{\isodoctype}{Draft International Standard} -\newcommand{\isodocstage}{(00) Preliminary} -% \newcommand{\isodocstage}{(10) Proposal} -% \newcommand{\isodocstage}{(20) Preparatory} -% \newcommand{\isodocstage}{(30) Committee} -% \newcommand{\isodocstage}{(40) Enquiry} -% \newcommand{\isodocstage}{(50) Approval} -% \newcommand{\isodocstage}{(60) Publication} +\newcommand{\isodocstage}{(00) Preliminary} \ No newline at end of file diff --git a/src/in_html.css b/src/in_html.css new file mode 100644 index 0000000..42cacc3 --- /dev/null +++ b/src/in_html.css @@ -0,0 +1,130 @@ +/* Information Preamble: Table like indented. */ + +#preamble div.hdlist { + margin-left: 50%; +} + +#preamble div.hdlist td.hdlist1 { + width: 11em; + padding: 0; +} + +#preamble div.hdlist td.hdlist2 p { + margin-bottom: 0.25em; +} + +/* Don't show section tags in ToC. */ +#toc .right { + /* display: none; */ +} + +/* Admonitions, i.e. notes. */ + +.admonitionblock > table { + width: auto; +} +.admonitionblock .icon { + vertical-align: top; + padding: 0 0.25em 0 0 !important; + width: fit-content !important; +} +.admonitionblock .icon .title { + text-transform: none !important; + width: fit-content !important; + font-weight: normal !important; + font-style: italic !important; + font-family: serif !important; + font-size: inherit !important; +} +.admonitionblock .content { + border: none !important; + padding: 0 !important; +} + +/* General formatting. */ + +.indented { + margin-left: 3em; +} + +.grammarterm { + font-style: italic; + font-family: sans-serif; +} + +.ucode::before { + content: "U+"; +} +.ucode, .uname { + font-family: serif; + font-style: normal; + text-transform: uppercase; +} + +.itemdescr { + margin-left: 3em; +} + +.large { + font-size: x-large; +} + +/* BNF grammar descriptions. */ + +.bnf { + margin-left: 3em; +} +.bnf dl dt { + font-weight: normal; + font-style: italic; + font-family: sans-serif; +} +.bnf dl dd { + margin-left: 3em; + font-weight: normal; + font-style: italic; + font-family: sans-serif; +} +.bnf .opt::after { + content: "opt"; + position: relative; + top: 0.25em; + font-size: 60%; +} +.bnf .descr { + font-style: normal; + font-family: serif; +} + +/* Examples. */ + +.exampleblock > .content::before { + content: "Example: "; + font-weight: normal !important; + font-style: italic !important; + font-family: serif !important; +} +.exampleblock > .content { + background: none; + border: none; + padding: 0; + box-shadow: none; +} + +/* Table of Contents. */ + +#toc ul.sectlevel1 > li { + margin-bottom: 1em; +} +#toc ul.sectlevel1 > li > a { + font-weight: bold; +} + +/* Cover pages. */ + +#covertitle { + margin: 5em 0 5em 0; +} +#covertitle .title { + font-size: 1.2em; +} diff --git a/src/in_macros.tex b/src/in_macros.tex index 0a62428..b01d843 100644 --- a/src/in_macros.tex +++ b/src/in_macros.tex @@ -357,10 +357,11 @@ \newcommand{\ctype}{\Fundesc{Type}} \newcommand{\templalias}{\Fundesc{Alias template}} -%% Scheme field descriptions +%% Schema field descriptions \newcommand{\fldname}{\Fundesc{Name}} \newcommand{\fldtype}{\Fundesc{Type}} \newcommand{\fldval}{\Fundesc{Value}} +\newcommand{\flditems}{\Fundesc{Items}} \newcommand{\flddesc}{\Fundesc{Description}} %% Cross-reference diff --git a/src/in_vars.adoc b/src/in_vars.adoc new file mode 100644 index 0000000..0088a6b --- /dev/null +++ b/src/in_vars.adoc @@ -0,0 +1,39 @@ +ifndef::in_vars[] +:in_vars: +:author: ISO C++ Tooling Study Group +:email: sg15@lists.isocpp.org +:license: Creative Commons Attribution 4.0 International License (CC BY 4.0) +:authors: René Ferdinand Rivera Morell +:copyright: Copyright {docyear} {authors} +:docno: D3342R1 +:disno: ----- +:isodocno: ISO/IEC {disno}:{docyear}(E) +:revdate: {docdate} +:prevdocno: +:doctitleen: Standard for C++ Ecosystem +:doctitlefr: Norme pour L'écosystème C++ +:isodoctype: Draft International Standard +:isodocstage00: (00) Preliminary +:isodocstage10: (10) Proposal +:isodocstage20: (20) Preparatory +:isodocstage30: (30) Committee +:isodocstage40: (40) Enquiry +:isodocstage50: (50) Approval +:isodocstage60: (60) Publication +:isodocstage: {isodocstage00} +:isocopyright_lic_on: © ISO/IEC {docyear} --- CC BY 4.0 +:isocopyright_lic_off: © ISO/IEC {docyear} --- All rights reserved +:doctype: book +:tex-source-highlighter: listings +:texroot: ecosystem.tex +:texindex: generalindex +ifeval::["{docstage}" == "draft"] +:doctitle: Working Draft, {doctitleen} +endif::[] +ifeval::["{docstage}" == "final"] +:doctitle: {doctitleen} +endif::[] +ifeval::["{docstage}" == "web"] +:doctitle: Working Draft, {doctitleen} +endif::[] +endif::[]