diff --git a/CHANGELOG.md b/CHANGELOG.md index 32eb776d..30bc6743 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,3 +3,7 @@ ## 2024-3-14 * Clean-up as part of Accellera Style Guide + +## 2024-11-21 + +* Separate Accellera Documentation Flow from documentation sources diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 00000000..d5f6f6d7 --- /dev/null +++ b/Dockerfile @@ -0,0 +1,115 @@ +# Dockerfile to create a ready-to-use docker image containing +# the Accelllera Documentation Flow using the Electric Book templates + +FROM ubuntu:22.04 + +# Main dependency installation +RUN apt-get update && apt-get install -y \ + software-properties-common \ + make \ + gcc \ + build-essential \ + git \ + wget \ + libgif7 \ + libpixman-1-0 \ + libffi-dev \ + libreadline-dev \ + zlib1g-dev \ + graphicsmagick \ + ruby-full + +# Dependencies specifically for Puppeteer on unix +#RUN apt-get install -y \ +# libasound2 \ +# libatk1.0-0 \ +# libatk-bridge2.0-0 \ +# libcairo2 \ +# libdrm2 \ +# libgbm1 \ +# libnss3 \ +# libpango-1.0-0 \ +# libxkbcommon-x11-0 \ +# libxcomposite1 \ +# libxdamage1 \ +# libxfixes3 \ +# libxrandr2 + +# Install Microsoft Core Fonts +RUN echo ttf-mscorefonts-installer msttcorefonts/accepted-mscorefonts-eula select true | debconf-set-selections +RUN apt-get install ttf-mscorefonts-installer -y + +# Add node source for new nodejs, instead of old Ubuntu-installed node. +# https://github.com/nodesource/distributions/wiki/How-to-migrate-to-the-new-repository + +# Update local package index +RUN apt-get update +# Install necessary packages for downloading and verifying new repository information +RUN apt-get install -y ca-certificates curl gnupg +# Create a directory for the new repository's keyring, if it doesn't exist +RUN mkdir -p /etc/apt/keyrings +# Download the new repository's GPG key and save it in the keyring directory +RUN curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg +# Add the new repository's source list with its GPG key for package verification +# Note: `node_20` means Node version 20. Update in future as needed. +RUN echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_20.x nodistro main" | tee /etc/apt/sources.list.d/nodesource.list +# Update local package index to recognize the new repository +RUN apt-get update +# Install Node.js from the new repository +RUN apt-get install -y nodejs + +# Install program to configure locales +RUN apt-get install -y locales +RUN dpkg-reconfigure locales && \ + locale-gen C.UTF-8 && \ + /usr/sbin/update-locale LANG=C.UTF-8 + +# Set default locale for the environment +ENV LC_ALL C.UTF-8 +ENV LANG en_US.UTF-8 +ENV LANGUAGE en_US.UTF-8 + +# Clear apt cache to make image smaller +RUN apt-get clean && rm -rf /var/lib/apt/lists/* /tmp/* + +# Install libssl1.1 +RUN wget http://archive.ubuntu.com/ubuntu/pool/main/o/openssl/libssl1.1_1.1.0g-2ubuntu4_amd64.deb && \ + dpkg -i libssl1.1_1.1.0g-2ubuntu4_amd64.deb + +# Install PrinceXML for printing to PDF +#RUN wget https://www.princexml.com/download/prince_11.4-1_ubuntu18.04_amd64.deb && \ +# dpkg -i prince_11.4-1_ubuntu18.04_amd64.deb + +# Install pandoc for document conversion +#RUN wget https://github.com/jgm/pandoc/releases/download/2.5/pandoc-2.5-1-amd64.deb && \ +# dpkg -i pandoc-2.5-1-amd64.deb + +# Update npm +RUN npm install -g npm@latest + +# Install Gulp cli app +RUN npm install --global gulp-cli + +# Install bundler and jekyll +RUN gem install jekyll bundler + +# Install gems. +COPY Gemfile . +RUN bash -lc "bundle install" + +# Switch to the user account +RUN useradd -ms /bin/bash adf +USER adf +WORKDIR /home/adf + +# Set paths for Ruby gems +RUN echo '# Define Ruby Gems path' >> ~/.bashrc +RUN echo 'export GEM_HOME="$HOME/.rvm/gems/ruby-2.7.6"' >> ~/.bashrc +RUN echo 'export PATH="$HOME/.rvm/gems/ruby-2.7.6:$PATH"' >> ~/.bashrc +RUN bash -lc "source ~/.bashrc" + +# Copy all flow elements to container +COPY --chown=adf:adf . . + +# Install Accellera Documentation Flow +RUN npm install diff --git a/Dockerfile.nocert b/Dockerfile.nocert new file mode 100644 index 00000000..5b5291db --- /dev/null +++ b/Dockerfile.nocert @@ -0,0 +1,118 @@ +# Dockerfile.nocert to create a ready-to-use docker image containing +# the Accelllera Documentation Flow using the Electric Book templates +# WARNING: This installation will disable TLS certificate checking +# and could lead tp security issues. Instead use the Dockerfile + +FROM ubuntu:22.04 + +# Main dependency installation +RUN apt-get update && apt-get install -y \ + software-properties-common \ + make \ + gcc \ + build-essential \ + git \ + wget \ + libgif7 \ + libpixman-1-0 \ + libffi-dev \ + libreadline-dev \ + zlib1g-dev \ + graphicsmagick \ + ruby-full + +# Dependencies specifically for Puppeteer on unix +#RUN apt-get install -y \ +# libasound2 \ +# libatk1.0-0 \ +# libatk-bridge2.0-0 \ +# libcairo2 \ +# libdrm2 \ +# libgbm1 \ +# libnss3 \ +# libpango-1.0-0 \ +# libxkbcommon-x11-0 \ +# libxcomposite1 \ +# libxdamage1 \ +# libxfixes3 \ +# libxrandr2 + +# Install Microsoft Core Fonts +RUN echo ttf-mscorefonts-installer msttcorefonts/accepted-mscorefonts-eula select true | debconf-set-selections +RUN apt-get install ttf-mscorefonts-installer -y + +# Add node source for new nodejs, instead of old Ubuntu-installed node. +# https://github.com/nodesource/distributions/wiki/How-to-migrate-to-the-new-repository + +# Update local package index +RUN apt-get update +# Install necessary packages for downloading and verifying new repository information +RUN apt-get install -y ca-certificates curl gnupg +# Create a directory for the new repository's keyring, if it doesn't exist +RUN mkdir -p /etc/apt/keyrings +# Download the new repository's GPG key and save it in the keyring directory +RUN curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg +# Add the new repository's source list with its GPG key for package verification +# Note: `node_20` means Node version 20. Update in future as needed. +RUN echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_20.x nodistro main" | tee /etc/apt/sources.list.d/nodesource.list +# Update local package index to recognize the new repository +RUN apt-get update +# Install Node.js from the new repository +RUN apt-get install -y nodejs + +# Install program to configure locales +RUN apt-get install -y locales +RUN dpkg-reconfigure locales && \ + locale-gen C.UTF-8 && \ + /usr/sbin/update-locale LANG=C.UTF-8 + +# Set default locale for the environment +ENV LC_ALL C.UTF-8 +ENV LANG en_US.UTF-8 +ENV LANGUAGE en_US.UTF-8 + +# Clear apt cache to make image smaller +RUN apt-get clean && rm -rf /var/lib/apt/lists/* /tmp/* + +# Install libssl1.1 +RUN wget http://archive.ubuntu.com/ubuntu/pool/main/o/openssl/libssl1.1_1.1.0g-2ubuntu4_amd64.deb && \ + dpkg -i libssl1.1_1.1.0g-2ubuntu4_amd64.deb + +# Install PrinceXML for printing to PDF +#RUN wget https://www.princexml.com/download/prince_11.4-1_ubuntu18.04_amd64.deb --no-check-certificate && \ +# dpkg -i prince_11.4-1_ubuntu18.04_amd64.deb + +# Install pandoc for document conversion +#RUN wget https://github.com/jgm/pandoc/releases/download/2.5/pandoc-2.5-1-amd64.deb --no-check-certificate && \ +# dpkg -i pandoc-2.5-1-amd64.deb + +# Update npm +RUN npm install -g npm@latest + +# Install Gulp cli app +RUN npm install --global gulp-cli + +# Install bundler and jekyll +RUN gem install jekyll bundler + +# Install gems. +COPY Gemfile . +RUN bash -lc "bundle install" + +# Switch to the user account +RUN useradd -ms /bin/bash adf +USER adf +WORKDIR /home/adf + +# Set paths for Ruby gems +RUN echo '# Define Ruby Gems path' >> ~/.bashrc +RUN echo 'export GEM_HOME="$HOME/.rvm/gems/ruby-2.7.6"' >> ~/.bashrc +RUN echo 'export PATH="$HOME/.rvm/gems/ruby-2.7.6:$PATH"' >> ~/.bashrc +RUN bash -lc "source ~/.bashrc" + +# Copy all flow elements to container +COPY --chown=adf:adf . . + +# Install Accellera Documentation Flow +ENV NODE_TLS_REJECT_UNAUTHORIZED=0 +RUN npm install diff --git a/README.md b/README.md index eef9026c..c84b5d47 100644 --- a/README.md +++ b/README.md @@ -1,17 +1,25 @@ -# Accellera Style Guide +# Accellera Documentation Flow (ADF) -## Document generation +The Accellera Documentation Flow offers the infrastructure to develop and publish Accellera (Draft) Standards, User Guides and other standard-related documentation. The main output are high-quality documents in Portable Document Format (PDF) compliant with the IEEE SA Standards Style Manual. Future extensions of this flow will also render interactive browser-compatible standards in HTML format. -To render the Accellera Style Guide, use the following command: +The documentation flow is documented in the Accellera Style Guide, which explains the Markdown formatting and styles to create IEEE SA Standards compliant documents. + +## Usage + +The document sources shall be located in directory `books//`. + +The document metadata (e.g. properties) shall be located in directory `_data/works//`. + +To render a PDF document using the Accellera Documentation Flow, use the following command: ```sh -npm run eb -- output --format screen-pdf --book accellera-style-guide +$ npm run eb -- output --format screen-pdf --book ``` -It will generate a PDF in the `_output` directory. +It will generate a PDF document in the `_output` directory. -Please contact the Technical Committee chair in case of questions on the Accellera documentation flow, the required installation procedure or use of the standard document templates. +Please contact the Technical Committee Chair in case of questions on the Accellera Documentation Flow, the required installation procedure or use of the standard document templates. ## Acknowledgment -Special thanks to [Electric Book Works](https://electricbookworks.com/) for the development and support of this technical documentation flow. \ No newline at end of file +Special thanks to [Electric Book Works](https://electricbookworks.com/) for the development and support of the Accellera Documentation Flow. diff --git a/_config.yml b/_config.yml index 14cd8f71..4bfdd057 100644 --- a/_config.yml +++ b/_config.yml @@ -37,7 +37,7 @@ canonical-url: "https://electricbookworks.github.io" # the name of your repo, e.g. /electric-book # It must start with a slash. Otherwise you can leave it blank. See: # http://downtothewire.io/2015/08/15/configuring-jekyll-for-user-and-project-github-pages/ -baseurl: "/accellera-style-guide" +baseurl: "" # GitHub Pages repository # ----------------------- @@ -113,6 +113,9 @@ exclude: - package-lock.json - CNAME - .sass-cache + - Docker* + - netlify.toml + - setup.sh # Included as-is in other files, no need to process - /assets/js/annotation.js @@ -148,6 +151,7 @@ exclude: # Files for formats we're not building here - /assets/profiles + - /books/* - /*/package.opf - /*/toc.ncx - /*/images/print-pdf diff --git a/_configs/_config.app.yml b/_configs/_config.app.yml index d27551d9..3c8f03f0 100644 --- a/_configs/_config.app.yml +++ b/_configs/_config.app.yml @@ -35,6 +35,9 @@ exclude: - package-lock.json - CNAME - .sass-cache + - Docker* + - netlify.toml + - setup.sh # Included as-is in other files, no need to process - /assets/js/annotation.js @@ -87,3 +90,5 @@ exclude: - /*/styles/screen-pdf* - /*/styles/web* - /*/styles/epub* + - /books/* + diff --git a/_configs/_config.epub.yml b/_configs/_config.epub.yml index 6b4c2c10..1b099a0d 100644 --- a/_configs/_config.epub.yml +++ b/_configs/_config.epub.yml @@ -24,6 +24,9 @@ exclude: - package.json - package-lock.json - CNAME + - Docker* + - netlify.toml + - setup.sh # Included as-is in other files, no need to process - /assets/js/annotation.js @@ -73,6 +76,7 @@ exclude: - /*/images/screen-pdf - /*/images/web - /*/images/app + - /books/* # Temporarily exclude book files for faster builds # - assets diff --git a/_configs/_config.live.yml b/_configs/_config.live.yml index 2498cd55..96f06a3d 100644 --- a/_configs/_config.live.yml +++ b/_configs/_config.live.yml @@ -31,6 +31,9 @@ exclude: - eslint.json - CHANGELOG.md - /*/images/source + - Docker* + - netlify.toml + - setup.sh # Included as-is in other files, no need to process - /assets/js/annotation.js @@ -84,6 +87,7 @@ exclude: - /*/styles/app* - /*/package.opf - /*/toc.ncx + - /books/* # Exclude web images only if you keep_files them below # - /*/images/web diff --git a/_configs/_config.print-pdf.yml b/_configs/_config.print-pdf.yml index 1b37a3bf..dae86c6b 100644 --- a/_configs/_config.print-pdf.yml +++ b/_configs/_config.print-pdf.yml @@ -25,6 +25,9 @@ exclude: - package-lock.json - CNAME - .sass-cache + - Docker* + - netlify.toml + - setup.sh # Included as-is in other files, no need to process - /assets/js/annotation.js @@ -91,6 +94,7 @@ exclude: - /*/images/web - /*/images/epub - /*/images/app + - /books/* # Temporarily exclude these and keep_files them below # for faster builds where you don't need to refresh these. diff --git a/_configs/_config.screen-pdf.yml b/_configs/_config.screen-pdf.yml index fe15a70c..44574f01 100644 --- a/_configs/_config.screen-pdf.yml +++ b/_configs/_config.screen-pdf.yml @@ -25,6 +25,9 @@ exclude: - package-lock.json - CNAME - .sass-cache + - Docker* + - netlify.toml + - setup.sh # Included as-is in other files, no need to process - /assets/js/annotation.js @@ -91,6 +94,7 @@ exclude: - /*/images/web - /*/images/epub - /*/images/app + - /books/* # Temporarily exclude these and keep_files them below # for faster builds where you don't need to refresh these. diff --git a/_data/works/accellera-standard-template/default.yml b/_data/works/accellera-standard-template/default.yml deleted file mode 100644 index d54aee31..00000000 --- a/_data/works/accellera-standard-template/default.yml +++ /dev/null @@ -1,78 +0,0 @@ -title: "Accellera Standard Template" -subtitle: "" -version: "version 0.1" -creator: "Accellera Systems Initiative" # E.g. the author -contributor: "" # E.g. other contributors -subject: "TEC008000" # E.g. BISAC terms (https://bisg.org/page/BISACEdition) or BIC (https://ns.editeur.org/bic_categories) -description: "This is the abstract of the Accellera Standard Template. This abstract is based on the description field in the document metadata which can be found in the file _data/works/standard/default.yml. When updating the description in this file, the description is also added to the PDF metadata." # E.g. the blurb -keywords: "accellera, standard, template" -publisher: "Accellera Systems Initiative" # E.g. the publisher, imprint or brand name -publisher-url: "" -date: "2024-04-30" # YYYY-MM-DD e.g. publication date -modified: "2024-04-30" # YYYY-MM-DD e.g. date of last revision -type: "Standard" # e.g. Standard, User Guide, Whitepaper -identifier: "" # e.g. ISBN or UUID -source: "" # e.g. parent ISBN or ISTC -language: "en" # use ISO 639-1, 639-2, or 639-3 codes (in that order of preference) -relation: "" # e.g. other edition ISBN -coverage: "" # e.g. geographic place or chronological time span -rightsholder: "Accellera" # who owns the copyright? -rights: "All rights reserved." # e.g. a copyright statement -image: "accellera_logo.svg" -status: "Final" # status, e.g., Draft, Final - -products: # Metadata for each product for this title (only use values that override parent metadata) - print-pdf: - date: "2024-04-30" # YYYY-MM-DD e.g. publication or creation date - format: "Print" # e.g. Paperback, Digital download, Digital online - identifier: "" # e.g. ISBN or UUID - image: "cover.jpg" - files: - toc: - screen-pdf: - date: "2024-01-03" # YYYY-MM-DD e.g. publication date or last revision - format: "Digital download" # e.g. Paperback, Digital download, Digital online - identifier: "" # e.g. ISBN or UUID - image: "cover.jpg" - files: - - "0-0-titlepage" - - "0-1-abstract" - - "0-2-notice" - - "0-3-introduction" - - "0-4-participants" - - "0-5-contents" - - "01" - - "02" - - "03" - - "04" - - "a" - toc: # For each menu item, include at least label and file. Optionally add id (for deep linking) and children. - - file: "01" - id: "1-overview" - label: "1. Overview" - children: - - file: "01" - id: "11-scope" - label: "1.1 Scope" - - file: "01" - id: "12-purpose" - label: "1.2 Purpose" - - file: "01" - id: "13-word-usage" - label: "1.3 Word usage" - - file: "02" - id: "2-normative-references" - label: "2. Normative references" - - file: "03" - id: "3-definitions-acronyms-and-abbreviations" - label: "3. Definitions, acronyms, and abbreviations" - children: - - file: "03" - id: "31-definitions" - label: "3.1 Definitions" - - file: "04" - id: "4-body-of-the-standard" - label: "4. Body of the standard" - - file: "a" - id: "annex-a" - label: "Annex A (informative) Title" diff --git a/_data/works/accellera-style-guide/default.yml b/_data/works/accellera-style-guide/default.yml index f85845ab..c4cffef6 100644 --- a/_data/works/accellera-style-guide/default.yml +++ b/_data/works/accellera-style-guide/default.yml @@ -1,15 +1,15 @@ title: "Accellera Style Guide" subtitle: "" -version: "version 0.3" +version: "version 0.5" creator: "Accellera Systems Initiative" # E.g. the author contributor: "" # E.g. other contributors -subject: "TEC008000" # E.g. BISAC terms (https://bisg.org/page/BISACEdition) or BIC (https://ns.editeur.org/bic_categories) +subject: "The Accellera Style Guide defines the recommended structure, formatting and style to develop and publish Accellera (Draft) Standards, User Guides and other standard-related documentation. This style guide serves as a reference for Accellera working groups in the technical editing process when drafting a standard-related document." description: "The Accellera Style Guide defines the recommended structure, formatting and style to develop Accellera Standards and Drafts." # E.g. the blurb keywords: "html, kramdown, markdown, style manual" publisher: "Accellera Systems Initiative" # E.g. the publisher, imprint or brand name publisher-url: "" -date: "2024-07-16" # YYYY-MM-DD e.g. publication date -modified: "2024-07-16" # YYYY-MM-DD e.g. date of last revision +date: "2024-12-02" # YYYY-MM-DD e.g. publication date +modified: "2024-12-02" # YYYY-MM-DD e.g. date of last revision type: "User Guide" # e.g. Standard, User Guide, Whitepaper identifier: "" # e.g. ISBN or UUID source: "" # e.g. parent ISBN or ISTC @@ -22,93 +22,8 @@ image: "accellera_logo.svg" status: "Final" # status, e.g., Draft, Final, Review products: # Metadata for each product for this title (only use values that override parent metadata) - print-pdf: - date: "2024-04-30" # YYYY-MM-DD e.g. publication or creation date - format: "Print" # e.g. Paperback, Digital download, Digital online - identifier: "" # e.g. ISBN or UUID - image: "cover.jpg" - files: - toc: - - file: "01" - id: "1-overview" - label: "1. Overview" - children: - - file: "01" - id: "11-purpose" - label: "1.1 Purpose" - - file: "01" - id: "12-helpful-resources" - label: "1.2 Helpful resources" - - file: "01" - id: "13-using-the-accellera-documentation-flow" - label: "1.3 Using the Accellera documentation flow" - - file: "02" - id: "2-project-setup" - label: "2. Project setup" - children: - - file: "02" - id: "21-github-repository-setup" - label: "2.1 GitHub repository setup" - - file: "02" - id: "22-accellera-standard-template" - label: "2.2 Accellera standard template" - - file: "02" - id: "23-tool-setup" - label: "2.3 Tool setup" - - file: "03" - id: "3-document-authoring-and-formatting" - label: "3. Document authoring and formatting" - children: - - file: "03" - id: "31-use-of-markdown-and-kramdown-syntax" - label: "3.1 Use of Markdown and kramdown syntax" - - file: "03" - id: "32-formatting-classes" - label: "3.2 Formatting classes" - - file: "04" - id: "4-document-structure-and-style" - label: "4. Document structure and style" - children: - - file: "04" - id: "41-frontmatter" - label: "4.1 Frontmatter" - - file: "04" - id: "42-document-body" - label: "4.2 Document body" - - file: "04" - id: "43-backmatter" - label: "4.3 Backmatter" - - file: "a" - id: "annex-a-informative-environment-setup" - label: "Annex A (informative) Environment setup" - children: - - file: "a" - id: "a1-download-virtualbox" - label: "A.1 Download VirtualBox" - - file: "a" - id: "a2-download-ubuntu-iso-image" - label: "A.2 Download Ubuntu ISO image" - - file: "a" - id: "a3-create-a-virtual-machine" - label: "A.3 Create a virtual machine" - - file: "a" - id: "a4-install-xubuntu" - label: "A.4 Install Xubuntu" - - file: "a" - id: "a5-install-documentation-flow" - label: "A.5 Install documentation flow" - - file: "b" - id: "annex-b-informative-electric-book-commands" - label: "Annex B (informative) Electric Book commands" - children: - - file: "b" - id: "b1-usage" - label: "B.1 Usage" - - file: "b" - id: "b2-examples" - label: "B.2 Examples" screen-pdf: - date: "2024-01-03" # YYYY-MM-DD e.g. publication date or last revision + date: "2024-12-02" # YYYY-MM-DD e.g. publication date or last revision format: "Digital download" # e.g. Paperback, Digital download, Digital online identifier: "" # e.g. ISBN or UUID image: "cover.jpg" @@ -116,88 +31,11 @@ products: # Metadata for each product for this title (only use values that overr - "0-0-titlepage" - "0-1-introduction" - "0-2-contents" + - "0-3-list-figures" + - "0-4-list-tables" - "01" - "02" - "03" - "04" - "a" - "b" - toc: - - file: "01" - id: "1-overview" - label: "1. Overview" - children: - - file: "01" - id: "11-purpose" - label: "1.1 Purpose" - - file: "01" - id: "12-helpful-resources" - label: "1.2 Helpful resources" - - file: "01" - id: "13-using-the-accellera-documentation-flow" - label: "1.3 Using the Accellera documentation flow" - - file: "02" - id: "2-project-setup" - label: "2. Project setup" - children: - - file: "02" - id: "21-github-repository-setup" - label: "2.1 GitHub repository setup" - - file: "02" - id: "22-accellera-standard-template" - label: "2.2 Accellera standard template" - - file: "02" - id: "23-tool-setup" - label: "2.3 Tool setup" - - file: "03" - id: "3-document-authoring-and-formatting" - label: "3. Document authoring and formatting" - children: - - file: "03" - id: "31-use-of-markdown-and-kramdown-syntax" - label: "3.1 Use of Markdown and kramdown syntax" - - file: "03" - id: "32-formatting-classes" - label: "3.2 Formatting classes" - - file: "04" - id: "4-document-structure-and-style" - label: "4. Document structure and style" - children: - - file: "04" - id: "41-frontmatter" - label: "4.1 Frontmatter" - - file: "04" - id: "42-document-body" - label: "4.2 Document body" - - file: "04" - id: "43-backmatter" - label: "4.3 Backmatter" - - file: "a" - id: "annex-a-informative-environment-setup" - label: "Annex A (informative) Environment setup" - children: - - file: "a" - id: "a1-download-virtualbox" - label: "A.1 Download VirtualBox" - - file: "a" - id: "a2-download-ubuntu-iso-image" - label: "A.2 Download Ubuntu ISO image" - - file: "a" - id: "a3-create-a-virtual-machine" - label: "A.3 Create a virtual machine" - - file: "a" - id: "a4-install-xubuntu" - label: "A.4 Install Xubuntu" - - file: "a" - id: "a5-install-documentation-flow" - label: "A.5 Install documentation flow" - - file: "b" - id: "annex-b-informative-electric-book-commands" - label: "Annex B (informative) Electric Book commands" - children: - - file: "b" - id: "b1-usage" - label: "B.1 Usage" - - file: "b" - id: "b2-examples" - label: "B.2 Examples" diff --git a/_data/works/cci/default.yml b/_data/works/cci/default.yml deleted file mode 100644 index 5204a035..00000000 --- a/_data/works/cci/default.yml +++ /dev/null @@ -1,303 +0,0 @@ -title: "SystemC Configuration, Control and Inspection Standard" -subtitle: "" -version: "CCI 1.0" -creator: "Accellera Systems Initiative" # E.g. the author -contributor: "" # E.g. other contributors -subject: "TEC008000" # E.g. BISAC terms (https://bisg.org/page/BISACEdition) or BIC (https://ns.editeur.org/bic_categories) -description: "This is the SystemC Configuration, Control and Inspection (CCI) Language Reference Manual." # E.g. the blurb -keywords: "Accellera Systems Initiative, SystemC, Configuration, CCI" -publisher: "Accellera Systems Initiative" # E.g. the publisher, imprint or brand name -publisher-url: "" -date: "2018-06-01" # YYYY-MM-DD e.g. publication date -modified: "2018-06-01" # YYYY-MM-DD e.g. date of last revision -type: "Standard" # e.g. Standard, User Guide, Whitepaper -identifier: "" # e.g. ISBN or UUID -source: "" # e.g. parent ISBN or ISTC -language: "en" # use ISO 639-1, 639-2, or 639-3 codes (in that order of preference) -relation: "" # e.g. other edition ISBN -coverage: "" # e.g. geographic place or chronological time span -rightsholder: "Accellera" # who owns the copyright? -rights: "All rights reserved." # e.g. a copyright statement -image: "accellera_logo.svg" -status: "Final" # status, e.g., Draft, Final - -products: # Metadata for each product for this title (only use values that override parent metadata) - print-pdf: - date: "2018-06-01" # YYYY-MM-DD e.g. publication or creation date - format: "Print" # e.g. Paperback, Digital download, Digital online - identifier: "" # e.g. ISBN or UUID - image: "cover.jpg" - files: - toc: - screen-pdf: - date: "2018-06-01" # YYYY-MM-DD e.g. publication date or last revision - format: "Digital download" # e.g. Paperback, Digital download, Digital online - identifier: "" # e.g. ISBN or UUID - image: "cover.jpg" - files: - - "0-0-titlepage" - - "0-1-abstract" - - "0-2-notice" - - "0-3-introduction" - - "0-4-participants" - - "0-5-contents" - - "01" - - "02" - - "03" - - "04" - - "05" - - "a" - - "b" - - "c" - - "d" - toc: - - file: "01" - id: "1-overview" - label: "1. Overview" - children: - - file: "01" - id: "11-scope" - label: "1.1 Scope" - - file: "01" - id: "12-purpose" - label: "1.2 Purpose" - - file: "01" - id: "13-word-usage" - label: "1.3 Word usage" - children: - - file: "01" - id: "131-relationship-with-c-isoiec-148822011" - label: "1.3.1 Relationship with C++ (ISO/IEC 14882:2011)" - - file: "01" - id: "132-relationship-with-systemc" - label: "1.3.2 Relationship with SystemC" - - file: "01" - id: "133-guidance-for-readers" - label: "1.3.3 Guidance for readers" - - file: "02" - id: "2-normative-references" - label: "2. Normative references" - - file: "03" - id: "3-terminology-and-conventions-used-in-this-standard" - label: "3. Terminology and conventions used in this standard" - children: - - file: "03" - id: "31-terminology" - label: "3.1 Terminology" - children: - - file: "03" - id: "311-shall-should-may-can" - label: "3.1.1 Shall, should, may, can" - - file: "03" - id: "312-application-implementation" - label: "3.1.2 Application, implementation" - - file: "03" - id: "313-call-called-from-derived-from" - label: "3.1.3 Call, called from, derived from" - - file: "03" - id: "314-specific-technical-terms" - label: "3.1.4 Specific technical terms" - - file: "03" - id: "32-syntactical-conventions" - label: "3.2 Syntactical conventions" - children: - - file: "03" - id: "321-implementation-defined" - label: "3.2.1 Implementation-defined" - - file: "03" - id: "322-ellipsis-" - label: "3.2.2 Ellipsis (…)" - - file: "03" - id: "323-class-names" - label: "3.2.3 Class names" - - file: "03" - id: "324-configuration-control-and-inspection-cci-naming-patterns" - label: "3.2.4 Configuration, Control and Inspection (CCI) naming patterns" - - file: "03" - id: "33-typographical-conventions" - label: "3.3 Typographical conventions" - - file: "03" - id: "34-semantic-conventions" - label: "3.4 Semantic conventions" - children: - - file: "03" - id: "341-class-definitions-and-the-inheritance-hierarchy" - label: "3.4.1 Class definitions and the inheritance hierarchy" - - file: "03" - id: "342-function-definitions-and-side-effects" - label: "3.4.2 Function definitions and side-effects" - - file: "03" - id: "343-exceptions" - label: "3.4.3 Exceptions" - - file: "03" - id: "344-functions-whose-return-type-is-a-reference-or-a-pointer" - label: "3.4.4 Functions whose return type is a reference or a pointer" - - file: "03" - id: "345-functions-that-return-this-or-a-pass-by-reference-argument" - label: "3.4.5 Functions that return *this or a pass-by-reference argument" - - file: "03" - id: "346-functions-that-return-const-char" - label: "3.4.6 Functions that return const char*" - - file: "03" - id: "347-non-compliant-applications-and-errors" - label: "3.4.7 Non-compliant applications and errors" - - file: "03" - id: "348-notes-and-examples" - label: "3.4.8 Notes and examples" - - file: "04" - id: "4-cci-architecture-overview" - label: "4. CCI architecture overview" - - file: "05" - id: "5-configuration-interfaces" - label: "5. Configuration interfaces" - children: - - file: "05" - id: "51-namespaces" - label: "5.1 Namespaces" - - file: "05" - id: "52-configuration-header-file" - label: "5.2 Configuration header file" - - file: "05" - id: "53-enumerations" - label: "5.3 Enumerations" - children: - - file: "05" - id: "531-cci_param_mutable_type" - label: "5.3.1 cci_param_mutable_type" - - file: "05" - id: "532-cci_param_data_category" - label: "5.3.2 cci_param_data_category" - - file: "05" - id: "533-cci_name_type" - label: "5.3.3 cci_name_type" - - file: "05" - id: "54-core-interfaces" - label: "5.4 Core interfaces" - children: - - file: "05" - id: "541-cci_originator" - label: "5.4.1 cci_originator" - - file: "05" - id: "542-cci_param_if" - label: "5.4.2 cci_param_if" - - file: "05" - id: "543-cci_broker_if" - label: "5.4.3 cci_broker_if" - - file: "05" - id: "55-variant-type-parameter-values" - label: "5.5 Variant type parameter values" - children: - - file: "05" - id: "551-cci_value_category" - label: "5.5.1 cci_value_category" - - file: "05" - id: "552-cci_value" - label: "5.5.2 cci_value" - - file: "05" - id: "553-cci_value_list" - label: "5.5.3 cci_value_list" - - file: "05" - id: "554-cci_value_map" - label: "5.5.4 cci_value_map" - - file: "05" - id: "56-parameters" - label: "5.6 Parameters" - children: - - file: "05" - id: "561-cci_param_untyped" - label: "5.6.1 cci_param_untyped" - - file: "05" - id: "562-cci_param_typed" - label: "5.6.2 cci_param_typed" - - file: "05" - id: "563-cci_param_untyped_handle" - label: "5.6.3 cci_param_untyped_handle" - - file: "05" - id: "564-cci_param_typed_handle" - label: "5.6.4 cci_param_typed_handle" - - file: "05" - id: "565-cci_param_write_event" - label: "5.6.5 cci_param_write_event" - - file: "05" - id: "57-brokers" - label: "5.7 Brokers" - children: - - file: "05" - id: "571-cci_broker_handle" - label: "5.7.1 cci_broker_handle" - - file: "05" - id: "572-cci_broker_manager" - label: "5.7.2 cci_broker_manager" - - file: "05" - id: "573-reference-brokers" - label: "5.7.3 Reference brokers" - - file: "05" - id: "58-error-reporting" - label: "5.8 Error reporting" - - file: "05" - id: "59-name-support-functions" - label: "5.9 Name support functions" - - file: "05" - id: "510-version-information" - label: "5.10 Version information" - - file: "a" - id: "annex-a-informative-a-introduction-to-systemc-configuration" - label: "Annex A (informative) A Introduction to SystemC Configuration" - children: - - file: "a" - id: "a1-sample-code" - label: "A.1 Sample code" - children: - - file: "a" - id: "a11-basic-parameter-use" - label: "A.1.1 Basic parameter use" - - file: "a" - id: "a12-parameter-handles" - label: "A.1.2 Parameter handles" - - file: "a" - id: "a13-enumerating-parameters" - label: "A.1.3 Enumerating parameters" - - file: "a" - id: "a14-preset-and-default-parameter-values" - label: "A.1.4 Preset and default parameter values" - - file: "a" - id: "a15-linking-parameters-with-callbacks" - label: "A.1.5 Linking parameters with callbacks" - - file: "a" - id: "a2--interface-classes" - label: "A.2 Interface classes" - children: - - file: "a" - id: "a21-cci_value" - label: "A.2.1 cci_value" - - file: "a" - id: "a22--cci_param" - label: "A.2.2 cci_param" - - file: "a" - id: "a23-cci_param_handle" - label: "A.2.3 cci_param_handle" - - file: "a" - id: "a3-error-reporting" - label: "A.3 Error reporting" - - file: "b" - id: "annex-b-informative-glossary" - label: "Annex B (informative) Glossary" - - file: "c" - id: "annex-c-informative-systemc-configuration-modeler-guidelines" - label: "Annex C (informative) SystemC Configuration modeler guidelines" - children: - - file: "c" - id: "c1-declare-parameter-instances-as-protected-or-private-members" - label: "C.1 Declare parameter instances as protected or private members" - - file: "c" - id: "c2-initialize-broker-handles-during-module-elaboration" - label: "C.2 Initialize broker handles during module elaboration" - - file: "c" - id: "c3-prefer-typed-parameter-value-access-over-untyped-when-possible-for-speed" - label: "C.3 Prefer typed parameter value access over untyped, when possible, for speed" - - file: "c" - id: "c4-provide-parameter-descriptions" - label: "C.4 Provide parameter descriptions" - - file: "d" - id: "annex-d-informative-enabling-user-defined-parameter-value-types" - label: "Annex D (informative) Enabling user-defined parameter value types" diff --git a/_data/works/ieee-sa-standard-template/default.yml b/_data/works/ieee-sa-standard-template/default.yml deleted file mode 100644 index 04fa18a4..00000000 --- a/_data/works/ieee-sa-standard-template/default.yml +++ /dev/null @@ -1,83 +0,0 @@ -title: "IEEE SA Standard Template" # Full name of the standard -subtitle: "" -version: "IEEE Pxxxx/Dx, [date]" # for drafts IEEE Pxxxx/Dx, [date] and for final version IEEE Std xxxx-[year] -creator: "Accellera Systems Initiative" # E.g. the author -contributor: "" # E.g. other contributors -subject: "" # E.g. BISAC terms (https://bisg.org/page/BISACEdition) or BIC (https://ns.editeur.org/bic_categories) -description: "Add Abstract—contents in the description field of the document metadata" # E.g. the blurb -keywords: "Add keywords using the document metadata" -publisher: "IEEE SA" # E.g. the publisher, imprint or brand name -publisher-url: "" -committee: "[Committee]" # E.g. P (mandatory for IEEE SA) -society: "[Society Name]" # E.g. Computer (mandatory for IEEE SA) -approved: "[XX MONTH 20XX]" # Approval date, notation DD MONTH YYYY (mandatory for IEEE SA) -isbn-pdf: "ISBN 978-0-XXXX-XXXX-X STDXXXXX" # ISBN Nr for PDF document (mandatory for IEEE SA) -isbn-print: "ISBN 978-0-XXXX-XXXX-X STDPDXXXXX" # ISBN Nr for Printed version (mandatory for IEEE SA) -date: "2024-04-30" # YYYY-MM-DD e.g. publication date -modified: "2024-04-30" # YYYY-MM-DD e.g. date of last revision -type: "Standard" # e.g. Standard, User Guide, Whitepaper -identifier: "" # e.g. ISBN or UUID -source: "" # e.g. parent ISBN or ISTC -language: "en" # use ISO 639-1, 639-2, or 639-3 codes (in that order of preference) -relation: "" # e.g. other edition ISBN -coverage: "" # e.g. geographic place or chronological time span -rightsholder: "IEEE" # who owns the copyright? -rights: "All rights reserved." # e.g. a copyright statement -image: "" -status: "Draft" # status, e.g., Draft, Final - -products: # Metadata for each product for this title (only use values that override parent metadata) - print-pdf: - date: "2024-04-30" # YYYY-MM-DD e.g. publication or creation date - format: "Print" # e.g. Paperback, Digital download, Digital online - identifier: "" # e.g. ISBN or UUID - image: "cover.jpg" - files: - toc: - screen-pdf: - date: "2024-01-03" # YYYY-MM-DD e.g. publication date or last revision - format: "Digital download" # e.g. Paperback, Digital download, Digital online - identifier: "" # e.g. ISBN or UUID - image: "cover.jpg" - files: - - "0-0-titlepage" - - "0-1-abstract" - - "0-2-notice" - - "0-3-participants" - - "0-4-introduction" - - "0-5-contents" - - "01" - - "02" - - "03" - - "04" - - "a" - toc: # For each menu item, include at least label and file. Optionally add id (for deep linking) and children. - - file: "01" - id: "1-overview" - label: "1. Overview" - children: - - file: "01" - id: "11-scope" - label: "1.1 Scope" - - file: "01" - id: "12-purpose" - label: "1.2 Purpose" - - file: "01" - id: "13-word-usage" - label: "1.3 Word usage" - - file: "02" - id: "2-normative-references" - label: "2. Normative references" - - file: "03" - id: "3-definitions-acronyms-and-abbreviations" - label: "3. Definitions, acronyms, and abbreviations" - children: - - file: "03" - id: "31-definitions" - label: "3.1 Definitions" - - file: "04" - id: "4-body-of-the-standard" - label: "4. Body of the standard" - - file: "a" - id: "annex-a" - label: "Annex A (informative) Title" diff --git a/_data/works/ieee-sa-standards-style-manual/default.yml b/_data/works/ieee-sa-standards-style-manual/default.yml index 2dc30bb1..b14f40a9 100644 --- a/_data/works/ieee-sa-standards-style-manual/default.yml +++ b/_data/works/ieee-sa-standards-style-manual/default.yml @@ -3,7 +3,7 @@ subtitle: "" version: "" creator: "IEEE" # E.g. the author contributor: "" # E.g. other contributors -subject: "TEC008000" # E.g. BISAC terms (https://bisg.org/page/BISACEdition) or BIC (https://ns.editeur.org/bic_categories) +subject: "" # E.g. BISAC terms (https://bisg.org/page/BISACEdition) or BIC (https://ns.editeur.org/bic_categories) description: "The IEEE Standards Style Manual (PDF) establishes preferred style for the preparation and structure of proposed IEEE standards (drafts). It also cites requirements of the *IEEE SA Standards Board Operations Manual* that are related to the development and publication of IEEE standards." # E.g. the blurb publisher: "IEEE" # E.g. the publisher, imprint or brand name publisher-url: "" @@ -21,814 +21,6 @@ image: "cover.jpg" status: "Final" # status, e.g., Draft, Final, Review products: # Metadata for each product for this title (only use values that override parent metadata) - print-pdf: - date: "2022-12-12" # YYYY-MM-DD e.g. publication or creation date - format: "Print" # e.g. Paperback, Digital download, Digital online - identifier: "" # e.g. ISBN or UUID - image: "cover.jpg" - files: - - "0-1-introduction" - - "0-2-contents" - - "01" - - "02" - - "03" - - "04" - - "05" - - "06" - - "07" - - "08" - - "09" - - "10" - - "11" - - "12" - - "13" - - "14" - - "15" - - "16" - - "17" - - "18" - - "19" - - "20" - - "21" - - "annex-a" - toc: # For each menu item, include at least label and file. Optionally add id (for deep linking) and children. - - file: "01" - id: "1-overview" - label: "1. Overview" - - file: "02" - id: "2-helpful-resources" - label: "2. Helpful resources" - children: - - file: "02" - id: "21-training-and-online-resources" - label: "2.1 Training and online resources" - - file: "02" - id: "22-documents" - label: "2.2 Documents" - - file: "03" - id: "3-using-ieee-sa-templates-to-write-the-draft" - label: "3. Using IEEE SA templates to write the draft" - - file: "04" - id: "4-responsibilities-of-the-standards-committee" - label: "4. Responsibilities of the standards committee" - - file: "05" - id: "5-copyright-and-permissions" - label: "5. Copyright and permissions" - children: - - file: "05" - id: "51-general-copyright-policy" - label: "5.1 General copyright policy" - - file: "05" - id: "52-excerpting-material-published-by-other-organizations" - label: "5.2 Excerpting material published by other organizations" - - file: "06" - id: "6-patents" - label: "6. Patents" - - file: "07" - id: "7-trademarks" - label: "7. Trademarks" - - file: "08" - id: "8-commercial-terms-and-conditions" - label: "8. Commercial terms and conditions" - - file: "09" - id: "9-standard-language-ie-shall-should-may-and-can" - label: "9. Standard language i.e., shall, should, may, and can" - - file: "10" - id: "10-additional-guidance-regarding-language-use-in-ieee-standards" - label: "10. Additional guidance regarding language use in IEEE standards" - children: - - file: "10" - id: "101-homogeneity" - label: "10.1 Homogeneity" - - file: "10" - id: "102-that-and-which" - label: "10.2 That and which" - - file: "10" - id: "103-absolute-verbiage" - label: "10.3 “Absolute” verbiage" - - file: "10" - id: "104-use-of-the-terms-safe-or-safety" - label: "10.4 Use of the terms safe or safety" - - file: "10" - id: "105-inclusive-language" - label: "10.5 Inclusive language" - - file: "10" - id: "106-use-of-personal-pronouns" - label: "10.6 Use of personal pronouns" - - file: "10" - id: "107-gender-specific-language" - label: "10.7 Gender specific language" - - file: "11" - id: "11-frontmatter-of-an-ieee-draft-standard" - label: "11. Frontmatter of an IEEE draft standard" - children: - - file: "11" - id: "111-general" - label: "11.1 General" - - file: "11" - id: "112-required-frontmatter-elements" - label: "11.2 Required frontmatter elements" - - file: "11" - id: "113-title" - label: "11.3 Title" - - file: "11" - id: "114-abstract-and-keywords" - label: "11.4 Abstract and keywords" - - file: "11" - id: "115-participant-lists" - label: "11.5 Participant lists" - - file: "11" - id: "116-introduction" - label: "11.6 Introduction" - - file: "11" - id: "117-permissions-list" - label: "11.7 Permissions list" - - file: "11" - id: "118-table-of-contents" - label: "11.8 Table of contents" - - file: "12" - id: "12-body-of-an-ieee-draft-standard" - label: "12. Body of an IEEE draft standard" - children: - - file: "12" - id: "121-normative-and-informative-clauses" - label: "12.1 Normative and informative clauses" - - file: "12" - id: "122-order-of-clauses" - label: "12.2 Order of clauses" - - file: "12" - id: "123-normative-references" - label: "12.3 Normative references" - - file: "12" - id: "124-definitions" - label: "12.4 Definitions" - - file: "12" - id: "125-acronyms-and-abbreviations" - label: "12.5 Acronyms and abbreviations" - - file: "12" - id: "126-annexes" - label: "12.6 Annexes" - - file: "12" - id: "127-indexes" - label: "12.7 Indexes" - - file: "13" - id: "13-numbering-the-clauses-and-subclauses-of-a-standard" - label: "13. Numbering the clauses and subclauses of a standard" - children: - - file: "13" - id: "131-body-clauses" - label: "13.1 Body clauses" - - file: "13" - id: "132-numbering-annexes" - label: "13.2 Numbering annexes" - - file: "13" - id: "133-lists" - label: "13.3 Lists" - - file: "14" - id: "14-quantities-units-and-letter-symbols" - label: "14. Quantities, units, and letter symbols" - children: - - file: "14" - id: "141-quantity" - label: "14.1 Quantity" - - file: "14" - id: "142-numbers" - label: "14.2 Numbers" - - file: "14" - id: "143-metric-system" - label: "14.3 Metric system" - - file: "14" - id: "144-letter-symbols" - label: "14.4 Letter symbols" - - file: "15" - id: "15-mathematical-expressions" - label: "15. Mathematical expressions" - children: - - file: "15" - id: "151-letter-symbols-and-units" - label: "15.1 Letter symbols and units" - - file: "15" - id: "152-numbering-of-equations" - label: "15.2 Numbering of equations" - - file: "15" - id: "153-presentation-of-equations" - label: "15.3 Presentation of equations" - - file: "15" - id: "154-quantity-and-numerical-value-equations" - label: "15.4 Quantity and numerical value equations" - - file: "16" - id: "16-tables" - label: "16. Tables" - children: - - file: "16" - id: "161-labeling-and-presentation-of-tables" - label: "16.1 Labeling and presentation of tables" - - file: "16" - id: "162-numbering-and-capitalization-in-tables" - label: "16.2 Numbering and capitalization in tables" - - file: "16" - id: "163-presentation-of-data-and-table-format" - label: "16.3 Presentation of data and table format" - - file: "16" - id: "164-notes-and-footnotes-to-tables" - label: "16.4 Notes and footnotes to tables" - - file: "16" - id: "165-informal-tables" - label: "16.5 Informal tables" - - file: "17" - id: "17-figures" - label: "17. Figures" - children: - - file: "17" - id: "171-requirements-for-creating-figures" - label: "17.1 Requirements for creating figures" - - file: "17" - id: "172-figure-numbering-and-titles" - label: "17.2 Figure numbering and titles" - - file: "17" - id: "173-notes-and-footnotes-to-figures" - label: "17.3 Notes and footnotes to figures" - - file: "18" - id: "18-notes-footnotes-examples-warnings-and-cautions" - label: "18. Notes, footnotes, examples, warnings, and cautions" - children: - - file: "18" - id: "181-notes" - label: "18.1 Notes" - - file: "18" - id: "182-footnotes" - label: "18.2 Footnotes" - - file: "18" - id: "183-examples" - label: "18.3 Examples" - - file: "18" - id: "184-warnings-and-cautions" - label: "18.4 Warnings and cautions" - - file: "19" - id: "19-bibliography" - label: "19. Bibliography" - children: - - file: "19" - id: "191-general" - label: "19.1 General" - - file: "19" - id: "192-citing-standards-in-a-bibliography" - label: "19.2 Citing standards in a bibliography" - - file: "19" - id: "193-articles-in-periodicals" - label: "19.3 Articles in periodicals" - - file: "19" - id: "194-books" - label: "19.4 Books" - - file: "20" - id: "20-amendments-corrigenda-and-errata" - label: "20. Amendments, corrigenda, and errata" - children: - - file: "20" - id: "201-general" - label: "20.1 General" - - file: "20" - id: "202-amendments-and-corrigenda" - label: "20.2 Amendments and corrigenda" - - file: "21" - id: "21-adoption-and-joint-development-overview" - label: "21. Adoption and joint development overview" - children: - - file: "21" - id: "211-style-for-ieee-documents-to-be-adopted-by-another-organization" - label: "21.1 Style for IEEE documents to be adopted by another organization" - - file: "21" - id: "212-ieee-documents-developed-jointly-with-other-organizations" - label: "21.2 IEEE documents developed jointly with other organizations" - - file: "annex-a" - id: "annex-a-normative-guidelines-and-best-practices-for-the-creation-and-maintenance-of-ieee-standards-terms-and-definitions" - label: "Annex A (normative) Guidelines and best practices for the creation and maintenance of IEEE standards terms and definitions" - web: - date: "2016-09-01" - - # Format - # e.g. Paperback, Digital download, Digital online - format: "Digital online" - - # E.g. ISBN or UUID - identifier: "" - - # Files to include in this format. - # On web, this determines pagination order. - files: - - "0-2-contents" - - "0-1-introduction" - - "01" - - "02" - - "03" - - "04" - - "05" - - "06" - - "07" - - "08" - - "09" - - "10" - - "11" - - "12" - - "13" - - "14" - - "15" - - "16" - - "17" - - "18" - - "19" - - "20" - - "21" - - "annex-a" - - # The web navigation for this book. - # Use same structure as 'toc:', - # though your nav might include different - # items to those in a book's TOC. - nav: - - label: "Introduction" - file: "0-1-introduction" - - label: "**1** Overview" - file: "01" - - label: "**2** Helpful resources" - children: - - file: "02" - id: "21-training-and-online-resources" - label: "2.1 Training and online resources" - - file: "02" - id: "22-documents" - label: "2.2 Documents" - - label: "**3** Using IEEE SA templates to write the draft" - file: "03" - - label: "**4** Responsibilities of the standards committee" - file: "04" - - label: "**5** Copyright and permissions" - children: - - file: "05" - id: "51-general-copyright-policy" - label: "5.1 General copyright policy" - - file: "05" - id: "52-excerpting-material-published-by-other-organizations" - label: "5.2 Excerpting material published by other organizations" - - file: "06" - label: "**6** Patents" - - file: "07" - label: "**7** Trademarks" - - file: "08" - label: "**8** Commercial terms and conditions" - - file: "09" - label: "**9** Standard language i.e., shall, should, may, and can" - - label: "**10** Additional guidance regarding language use in IEEE standards" - children: - - file: "10" - id: "101-homogeneity" - label: "10.1 Homogeneity" - - file: "10" - id: "102-that-and-which" - label: "10.2 That and which" - - file: "10" - id: "103-absolute-verbiage" - label: "10.3 “Absolute” verbiage" - - file: "10" - id: "104-use-of-the-terms-safe-or-safety" - label: "10.4 Use of the terms safe or safety" - - file: "10" - id: "105-inclusive-language" - label: "10.5 Inclusive language" - - file: "10" - id: "106-use-of-personal-pronouns" - label: "10.6 Use of personal pronouns" - - file: "10" - id: "107-gender-specific-language" - label: "10.7 Gender specific language" - - label: "**11** Frontmatter of an IEEE draft standard" - children: - - file: "11" - id: "111-general" - label: "11.1 General" - - file: "11" - id: "112-required-frontmatter-elements" - label: "11.2 Required frontmatter elements" - - file: "11" - id: "113-title" - label: "11.3 Title" - - file: "11" - id: "114-abstract-and-keywords" - label: "11.4 Abstract and keywords" - - file: "11" - id: "115-participant-lists" - label: "11.5 Participant lists" - - file: "11" - id: "116-introduction" - label: "11.6 Introduction" - - file: "11" - id: "117-permissions-list" - label: "11.7 Permissions list" - - file: "11" - id: "118-table-of-contents" - label: "11.8 Table of contents" - - label: "**12** Body of an IEEE draft standard" - children: - - file: "12" - id: "121-normative-and-informative-clauses" - label: "12.1 Normative and informative clauses" - - file: "12" - id: "122-order-of-clauses" - label: "12.2 Order of clauses" - - file: "12" - id: "123-normative-references" - label: "12.3 Normative references" - - file: "12" - id: "124-definitions" - label: "12.4 Definitions" - - file: "12" - id: "125-acronyms-and-abbreviations" - label: "12.5 Acronyms and abbreviations" - - file: "12" - id: "126-annexes" - label: "12.6 Annexes" - - file: "12" - id: "127-indexes" - label: "12.7 Indexes" - - label: "**13** Numbering the clauses and subclauses of a standard" - children: - - file: "13" - id: "131-body-clauses" - label: "13.1 Body clauses" - - file: "13" - id: "132-numbering-annexes" - label: "13.2 Numbering annexes" - - file: "13" - id: "133-lists" - label: "13.3 Lists" - - label: "**14** Quantities, units, and letter symbols" - children: - - file: "14" - id: "141-quantity" - label: "14.1 Quantity" - - file: "14" - id: "142-numbers" - label: "14.2 Numbers" - - file: "14" - id: "143-metric-system" - label: "14.3 Metric system" - - file: "14" - id: "144-letter-symbols" - label: "14.4 Letter symbols" - - label: "**15** Mathematical expressions" - children: - - file: "15" - id: "151-letter-symbols-and-units" - label: "15.1 Letter symbols and units" - - file: "15" - id: "152-numbering-of-equations" - label: "15.2 Numbering of equations" - - file: "15" - id: "153-presentation-of-equations" - label: "15.3 Presentation of equations" - - file: "15" - id: "154-quantity-and-numerical-value-equations" - label: "15.4 Quantity and numerical value equations" - - label: "**16** Tables" - children: - - file: "16" - id: "161-labeling-and-presentation-of-tables" - label: "16.1 Labeling and presentation of tables" - - file: "16" - id: "162-numbering-and-capitalization-in-tables" - label: "16.2 Numbering and capitalization in tables" - - file: "16" - id: "163-presentation-of-data-and-table-format" - label: "16.3 Presentation of data and table format" - - file: "16" - id: "164-notes-and-footnotes-to-tables" - label: "16.4 Notes and footnotes to tables" - - file: "16" - id: "165-informal-tables" - label: "16.5 Informal tables" - - label: "**17** Figures" - children: - - file: "17" - id: "171-requirements-for-creating-figures" - label: "17.1 Requirements for creating figures" - - file: "17" - id: "172-figure-numbering-and-titles" - label: "17.2 Figure numbering and titles" - - file: "17" - id: "173-notes-and-footnotes-to-figures" - label: "17.3 Notes and footnotes to figures" - - label: "**18** Notes, footnotes, examples, warnings, and cautions" - children: - - file: "18" - id: "181-notes" - label: "18.1 Notes" - - file: "18" - id: "182-footnotes" - label: "18.2 Footnotes" - - file: "18" - id: "183-examples" - label: "18.3 Examples" - - file: "18" - id: "184-warnings-and-cautions" - label: "18.4 Warnings and cautions" - - label: "**19** Bibliography" - children: - - file: "19" - id: "191-general" - label: "19.1 General" - - file: "19" - id: "192-citing-standards-in-a-bibliography" - label: "19.2 Citing standards in a bibliography" - - file: "19" - id: "193-articles-in-periodicals" - label: "19.3 Articles in periodicals" - - file: "19" - id: "194-books" - label: "19.4 Books" - - label: "**20** Amendments, corrigenda, and errata" - children: - - file: "20" - id: "201-general" - label: "20.1 General" - - file: "20" - id: "202-amendments-and-corrigenda" - label: "20.2 Amendments and corrigenda" - - label: "**21** Adoption and joint development overview" - children: - - file: "21" - id: "211-style-for-ieee-documents-to-be-adopted-by-another-organization" - label: "21.1 Style for IEEE documents to be adopted by another organization" - - file: "21" - id: "212-ieee-documents-developed-jointly-with-other-organizations" - label: "21.2 IEEE documents developed jointly with other organizations" - - file: "annex-a" - label: "Annex A (normative) Guidelines and best practices for the creation and maintenance of IEEE standards terms and definitions" - - toc: - - label: "Introduction" - file: "0-1-introduction" - - label: "1. Overview" - file: "01" - - label: "2. Helpful resources" - file: "02" - children: - - file: "02" - id: "21-training-and-online-resources" - label: "2.1 Training and online resources" - - file: "02" - id: "22-documents" - label: "2.2 Documents" - - label: "3. Using IEEE SA templates to write the draft" - file: "03" - - label: "4. Responsibilities of the standards committee" - file: "04" - - label: "5. Copyright and permissions" - file: "05" - children: - - file: "05" - id: "51-general-copyright-policy" - label: "5.1 General copyright policy" - - file: "05" - id: "52-excerpting-material-published-by-other-organizations" - label: "5.2 Excerpting material published by other organizations" - - file: "06" - label: "6. Patents" - - file: "07" - label: "7. Trademarks" - - file: "08" - label: "8. Commercial terms and conditions" - - file: "09" - label: "9. Standard language i.e., shall, should, may, and can" - - label: "10. Additional guidance regarding language use in IEEE standards" - file: "10" - children: - - file: "10" - id: "101-homogeneity" - label: "10.1 Homogeneity" - - file: "10" - id: "102-that-and-which" - label: "10.2 That and which" - - file: "10" - id: "103-absolute-verbiage" - label: "10.3 “Absolute” verbiage" - - file: "10" - id: "104-use-of-the-terms-safe-or-safety" - label: "10.4 Use of the terms safe or safety" - - file: "10" - id: "105-inclusive-language" - label: "10.5 Inclusive language" - - file: "10" - id: "106-use-of-personal-pronouns" - label: "10.6 Use of personal pronouns" - - file: "10" - id: "107-gender-specific-language" - label: "10.7 Gender specific language" - - label: "11. Frontmatter of an IEEE draft standard" - file: "11" - children: - - file: "11" - id: "111-general" - label: "11.1 General" - - file: "11" - id: "112-required-frontmatter-elements" - label: "11.2 Required frontmatter elements" - - file: "11" - id: "113-title" - label: "11.3 Title" - - file: "11" - id: "114-abstract-and-keywords" - label: "11.4 Abstract and keywords" - - file: "11" - id: "115-participant-lists" - label: "11.5 Participant lists" - - file: "11" - id: "116-introduction" - label: "11.6 Introduction" - - file: "11" - id: "117-permissions-list" - label: "11.7 Permissions list" - - file: "11" - id: "118-table-of-contents" - label: "11.8 Table of contents" - - label: "12. Body of an IEEE draft standard" - file: "12" - children: - - file: "12" - id: "121-normative-and-informative-clauses" - label: "12.1 Normative and informative clauses" - - file: "12" - id: "122-order-of-clauses" - label: "12.2 Order of clauses" - - file: "12" - id: "123-normative-references" - label: "12.3 Normative references" - - file: "12" - id: "124-definitions" - label: "12.4 Definitions" - - file: "12" - id: "125-acronyms-and-abbreviations" - label: "12.5 Acronyms and abbreviations" - - file: "12" - id: "126-annexes" - label: "12.6 Annexes" - - file: "12" - id: "127-indexes" - label: "12.7 Indexes" - - label: "13. Numbering the clauses and subclauses of a standard" - file: "13" - children: - - file: "13" - id: "131-body-clauses" - label: "13.1 Body clauses" - - file: "13" - id: "132-numbering-annexes" - label: "13.2 Numbering annexes" - - file: "13" - id: "133-lists" - label: "13.3 Lists" - - label: "14. Quantities, units, and letter symbols" - file: "14" - children: - - file: "14" - id: "141-quantity" - label: "14.1 Quantity" - - file: "14" - id: "142-numbers" - label: "14.2 Numbers" - - file: "14" - id: "143-metric-system" - label: "14.3 Metric system" - - file: "14" - id: "144-letter-symbols" - label: "14.4 Letter symbols" - - label: "15. Mathematical expressions" - file: "15" - children: - - file: "15" - id: "151-letter-symbols-and-units" - label: "15.1 Letter symbols and units" - - file: "15" - id: "152-numbering-of-equations" - label: "15.2 Numbering of equations" - - file: "15" - id: "153-presentation-of-equations" - label: "15.3 Presentation of equations" - - file: "15" - id: "154-quantity-and-numerical-value-equations" - label: "15.4 Quantity and numerical value equations" - - label: "16. Tables" - file: "16" - children: - - file: "16" - id: "161-labeling-and-presentation-of-tables" - label: "16.1 Labeling and presentation of tables" - - file: "16" - id: "162-numbering-and-capitalization-in-tables" - label: "16.2 Numbering and capitalization in tables" - - file: "16" - id: "163-presentation-of-data-and-table-format" - label: "16.3 Presentation of data and table format" - - file: "16" - id: "164-notes-and-footnotes-to-tables" - label: "16.4 Notes and footnotes to tables" - - file: "16" - id: "165-informal-tables" - label: "16.5 Informal tables" - - label: "17. Figures" - file: "17" - children: - - file: "17" - id: "171-requirements-for-creating-figures" - label: "17.1 Requirements for creating figures" - - file: "17" - id: "172-figure-numbering-and-titles" - label: "17.2 Figure numbering and titles" - - file: "17" - id: "173-notes-and-footnotes-to-figures" - label: "17.3 Notes and footnotes to figures" - - label: "18. Notes, footnotes, examples, warnings, and cautions" - file: "18" - children: - - file: "18" - id: "181-notes" - label: "18.1 Notes" - - file: "18" - id: "182-footnotes" - label: "18.2 Footnotes" - - file: "18" - id: "183-examples" - label: "18.3 Examples" - - file: "18" - id: "184-warnings-and-cautions" - label: "18.4 Warnings and cautions" - - label: "19. Bibliography" - file: "19" - children: - - file: "19" - id: "191-general" - label: "19.1 General" - - file: "19" - id: "192-citing-standards-in-a-bibliography" - label: "19.2 Citing standards in a bibliography" - - file: "19" - id: "193-articles-in-periodicals" - label: "19.3 Articles in periodicals" - - file: "19" - id: "194-books" - label: "19.4 Books" - - label: "20. Amendments, corrigenda, and errata" - file: "20" - children: - - file: "20" - id: "201-general" - label: "20.1 General" - - file: "20" - id: "202-amendments-and-corrigenda" - label: "20.2 Amendments and corrigenda" - - label: "21. Adoption and joint development overview" - file: "21" - children: - - file: "21" - id: "211-style-for-ieee-documents-to-be-adopted-by-another-organization" - label: "21.1 Style for IEEE documents to be adopted by another organization" - - file: "21" - id: "212-ieee-documents-developed-jointly-with-other-organizations" - label: "21.2 IEEE documents developed jointly with other organizations" - - file: "annex-a" - label: "Annex A (normative) Guidelines and best practices for the creation and maintenance of IEEE standards terms and definitions" - - # At which file should users start reading? - start-page: "0-2-contents" - - # Your contents-page file, if you have one. - contents-page: "0-2-contents" - epub: - date: "2016-05-07" # YYYY-MM-DD e.g. publication date or last revision - format: "Digital download" # e.g. Paperback, Digital download, Digital online - identifier: "9780000000000" # e.g. ISBN or UUID - image: "cover.jpg" - start-page: "0-3-contents" - contents-page: "0-3-contents" - files: # add a value to any file to set any of the guide types listed in http://www.idpf.org/epub/20/spec/OPF_2.0.1_draft.htm#Section2.6 - - "0-0-cover": "cover" - - "0-1-titlepage": "title-page" - - "0-2-copyright": "copyright-page" - - "0-3-contents": "toc" - - "01": "text" - - "02" - toc: # For each menu item, include at least label and file (epub requires file). Optionally add id (for deep linking) and children. - - label: "Cover" - file: "0-0-cover" - - label: "Title page" - file: "0-1-titlepage" - - label: "Copyright" - file: "0-2-copyright" - - label: "Contents" - file: "0-3-contents" - - label: "Chapter One" - file: "01" - - label: "Chapter Two" - file: "02" screen-pdf: date: "2016-05-07" # YYYY-MM-DD e.g. publication date or last revision format: "Digital download" # e.g. Paperback, Digital download, Digital online @@ -860,256 +52,3 @@ products: # Metadata for each product for this title (only use values that overr - "20" - "21" - "annex-a" - toc: # For each menu item, include at least label and file. Optionally add id (for deep linking) and children. - - file: "01" - id: "1-overview" - label: "1. Overview" - - file: "02" - id: "2-helpful-resources" - label: "2. Helpful resources" - children: - - file: "02" - id: "21-training-and-online-resources" - label: "2.1 Training and online resources" - - file: "02" - id: "22-documents" - label: "2.2 Documents" - - file: "03" - id: "3-using-ieee-sa-templates-to-write-the-draft" - label: "3. Using IEEE SA templates to write the draft" - - file: "04" - id: "4-responsibilities-of-the-standards-committee" - label: "4. Responsibilities of the standards committee" - - file: "05" - id: "5-copyright-and-permissions" - label: "5. Copyright and permissions" - children: - - file: "05" - id: "51-general-copyright-policy" - label: "5.1 General copyright policy" - - file: "05" - id: "52-excerpting-material-published-by-other-organizations" - label: "5.2 Excerpting material published by other organizations" - - file: "06" - id: "6-patents" - label: "6. Patents" - - file: "07" - id: "7-trademarks" - label: "7. Trademarks" - - file: "08" - id: "8-commercial-terms-and-conditions" - label: "8. Commercial terms and conditions" - - file: "09" - id: "9-standard-language-ie-shall-should-may-and-can" - label: "9. Standard language i.e., shall, should, may, and can" - - file: "10" - id: "10-additional-guidance-regarding-language-use-in-ieee-standards" - label: "10. Additional guidance regarding language use in IEEE standards" - children: - - file: "10" - id: "101-homogeneity" - label: "10.1 Homogeneity" - - file: "10" - id: "102-that-and-which" - label: "10.2 That and which" - - file: "10" - id: "103-absolute-verbiage" - label: "10.3 “Absolute” verbiage" - - file: "10" - id: "104-use-of-the-terms-safe-or-safety" - label: "10.4 Use of the terms safe or safety" - - file: "10" - id: "105-inclusive-language" - label: "10.5 Inclusive language" - - file: "10" - id: "106-use-of-personal-pronouns" - label: "10.6 Use of personal pronouns" - - file: "10" - id: "107-gender-specific-language" - label: "10.7 Gender specific language" - - file: "11" - id: "11-frontmatter-of-an-ieee-draft-standard" - label: "11. Frontmatter of an IEEE draft standard" - children: - - file: "11" - id: "111-general" - label: "11.1 General" - - file: "11" - id: "112-required-frontmatter-elements" - label: "11.2 Required frontmatter elements" - - file: "11" - id: "113-title" - label: "11.3 Title" - - file: "11" - id: "114-abstract-and-keywords" - label: "11.4 Abstract and keywords" - - file: "11" - id: "115-participant-lists" - label: "11.5 Participant lists" - - file: "11" - id: "116-introduction" - label: "11.6 Introduction" - - file: "11" - id: "117-permissions-list" - label: "11.7 Permissions list" - - file: "11" - id: "118-table-of-contents" - label: "11.8 Table of contents" - - file: "12" - id: "12-body-of-an-ieee-draft-standard" - label: "12. Body of an IEEE draft standard" - children: - - file: "12" - id: "121-normative-and-informative-clauses" - label: "12.1 Normative and informative clauses" - - file: "12" - id: "122-order-of-clauses" - label: "12.2 Order of clauses" - - file: "12" - id: "123-normative-references" - label: "12.3 Normative references" - - file: "12" - id: "124-definitions" - label: "12.4 Definitions" - - file: "12" - id: "125-acronyms-and-abbreviations" - label: "12.5 Acronyms and abbreviations" - - file: "12" - id: "126-annexes" - label: "12.6 Annexes" - - file: "12" - id: "127-indexes" - label: "12.7 Indexes" - - file: "13" - id: "13-numbering-the-clauses-and-subclauses-of-a-standard" - label: "13. Numbering the clauses and subclauses of a standard" - children: - - file: "13" - id: "131-body-clauses" - label: "13.1 Body clauses" - - file: "13" - id: "132-numbering-annexes" - label: "13.2 Numbering annexes" - - file: "13" - id: "133-lists" - label: "13.3 Lists" - - file: "14" - id: "14-quantities-units-and-letter-symbols" - label: "14. Quantities, units, and letter symbols" - children: - - file: "14" - id: "141-quantity" - label: "14.1 Quantity" - - file: "14" - id: "142-numbers" - label: "14.2 Numbers" - - file: "14" - id: "143-metric-system" - label: "14.3 Metric system" - - file: "14" - id: "144-letter-symbols" - label: "14.4 Letter symbols" - - file: "15" - id: "15-mathematical-expressions" - label: "15. Mathematical expressions" - children: - - file: "15" - id: "151-letter-symbols-and-units" - label: "15.1 Letter symbols and units" - - file: "15" - id: "152-numbering-of-equations" - label: "15.2 Numbering of equations" - - file: "15" - id: "153-presentation-of-equations" - label: "15.3 Presentation of equations" - - file: "15" - id: "154-quantity-and-numerical-value-equations" - label: "15.4 Quantity and numerical value equations" - - file: "16" - id: "16-tables" - label: "16. Tables" - children: - - file: "16" - id: "161-labeling-and-presentation-of-tables" - label: "16.1 Labeling and presentation of tables" - - file: "16" - id: "162-numbering-and-capitalization-in-tables" - label: "16.2 Numbering and capitalization in tables" - - file: "16" - id: "163-presentation-of-data-and-table-format" - label: "16.3 Presentation of data and table format" - - file: "16" - id: "164-notes-and-footnotes-to-tables" - label: "16.4 Notes and footnotes to tables" - - file: "16" - id: "165-informal-tables" - label: "16.5 Informal tables" - - file: "17" - id: "17-figures" - label: "17. Figures" - children: - - file: "17" - id: "171-requirements-for-creating-figures" - label: "17.1 Requirements for creating figures" - - file: "17" - id: "172-figure-numbering-and-titles" - label: "17.2 Figure numbering and titles" - - file: "17" - id: "173-notes-and-footnotes-to-figures" - label: "17.3 Notes and footnotes to figures" - - file: "18" - id: "18-notes-footnotes-examples-warnings-and-cautions" - label: "18. Notes, footnotes, examples, warnings, and cautions" - children: - - file: "18" - id: "181-notes" - label: "18.1 Notes" - - file: "18" - id: "182-footnotes" - label: "18.2 Footnotes" - - file: "18" - id: "183-examples" - label: "18.3 Examples" - - file: "18" - id: "184-warnings-and-cautions" - label: "18.4 Warnings and cautions" - - file: "19" - id: "19-bibliography" - label: "19. Bibliography" - children: - - file: "19" - id: "191-general" - label: "19.1 General" - - file: "19" - id: "192-citing-standards-in-a-bibliography" - label: "19.2 Citing standards in a bibliography" - - file: "19" - id: "193-articles-in-periodicals" - label: "19.3 Articles in periodicals" - - file: "19" - id: "194-books" - label: "19.4 Books" - - file: "20" - id: "20-amendments-corrigenda-and-errata" - label: "20. Amendments, corrigenda, and errata" - children: - - file: "20" - id: "201-general" - label: "20.1 General" - - file: "20" - id: "202-amendments-and-corrigenda" - label: "20.2 Amendments and corrigenda" - - file: "21" - id: "21-adoption-and-joint-development-overview" - label: "21. Adoption and joint development overview" - children: - - file: "21" - id: "211-style-for-ieee-documents-to-be-adopted-by-another-organization" - label: "21.1 Style for IEEE documents to be adopted by another organization" - - file: "21" - id: "212-ieee-documents-developed-jointly-with-other-organizations" - label: "21.2 IEEE documents developed jointly with other organizations" - - file: "annex-a" - id: "annex-a-normative-guidelines-and-best-practices-for-the-creation-and-maintenance-of-ieee-standards-terms-and-definitions" - label: "Annex A (normative) Guidelines and best practices for the creation and maintenance of IEEE standards terms and definitions" - diff --git a/_includes/list-of-figures b/_includes/list-of-figures new file mode 100644 index 00000000..6efab97c --- /dev/null +++ b/_includes/list-of-figures @@ -0,0 +1,6 @@ +{% comment %} +Extracted List of Figures will be added as part of HTML DOM processing. +We only need to add the list-of-figures placeholder here +{% endcomment %} + +
    diff --git a/_includes/list-of-tables b/_includes/list-of-tables new file mode 100644 index 00000000..46de8e07 --- /dev/null +++ b/_includes/list-of-tables @@ -0,0 +1,6 @@ +{% comment %} +Extracted List of Tables will be added as part of HTML DOM processing. +We only need to add the list-of-tables placeholder here +{% endcomment %} + +
      diff --git a/_includes/metadata b/_includes/metadata index 6fb8c5ce..a2ccb967 100644 --- a/_includes/metadata +++ b/_includes/metadata @@ -388,6 +388,7 @@ be sure we're pointing to the webserver root.{% endcomment %} {% endif %} {% comment %}Create a short tag for the path to images.{% endcomment %} + {% capture images %}{{ path-to-book-directory }}{{ site.image-set }}{% endcapture %} {% comment %} diff --git a/_includes/table b/_includes/table index 8afb225d..cf18df39 100644 --- a/_includes/table +++ b/_includes/table @@ -1,40 +1,33 @@ {% capture this-table %} -{% comment %} -To do: create HTML5
      option here based on site.output -{% endcomment %} {% include metadata %} {% comment %} Check the reference. If it's the same as the image name, hide it. -This allows for figures with IDs but without visible references. {% endcomment %} +This allows for tables with IDs but without visible references. {% endcomment %} {% assign table-reference-hidden = false %} {% capture table-reference %}{{ include.reference }}{% endcapture %} -{% comment %} -TODO: replace figure css styles by table css style -{% endcomment %} - -
      -
      +
      +
      {% if include.slide-caption == nil and include.caption-position == "top" %} {% if table-reference-hidden == false or include.caption and include.caption != "" %}

      - {% if table-reference and table-reference-hidden == false %}{{ table-reference }}{% endif %}{{ include.caption | markdownify | remove: '

      ' | remove: '

      ' | strip_newlines }} + {% if table-reference and table-reference-hidden == false %}{{ table-reference }}{% endif %}{{ include.caption | markdownify | remove: '

      ' | remove: '

      ' | strip_newlines }}

      {% endif %} {% endif %} {% if include.html and include.html != "" %} -
      +
      {{ include.html }}
      {% endif %} {% if include.markdown and include.markdown != "" %} -
      +
      {{ include.markdown | markdownify }}
      {% endif %} @@ -54,26 +47,24 @@ TODO: replace figure css styles by table css style {% if include.slide-caption == nil and include.caption-position != "top" %} {% if table-reference-hidden == false or include.caption and include.caption != "" %} -

      - {% if table-reference and table-reference-hidden == false %}{{ table-reference }}{% endif %}{{ include.caption | markdownify | remove: '

      ' | remove: '

      ' | strip_newlines }} +

      + {% if table-reference and table-reference-hidden == false %}{{ table-reference }}{% endif %}{{ include.caption | markdownify | remove: '

      ' | remove: '

      ' | strip_newlines }}

      {% endif %} {% endif %} -
      +
      {% if include.source and include.source != "" %} - -
      +

      {{ include.source | markdownify | remove: '

      ' | remove: '

      ' | strip_newlines }}

      -
      - +
      {% endif %} -
      +
      {% endcapture %} {{ this-table }} diff --git a/_includes/toc b/_includes/toc index 5fa8202e..4e4ccff5 100644 --- a/_includes/toc +++ b/_includes/toc @@ -1,173 +1,6 @@ {% comment %} -Get the file metadata. +Extracted ToC will be added as part of HTML DOM processing. +We only need to add the toc placeholder here {% endcomment %} -{% include metadata %} -{% comment %} -Now check which output format we're creating, and capture its toc. -Fall back to print-pdf toc, then web nav list. -{% endcomment %} - -{% comment %} Create a flag for when there is -no toc in _data/works YAML. {% endcomment %} -{% assign use-files-for-toc = false %} - -{% unless include.start %} - - {% if site.output == "print-pdf" %} - {% if print-pdf-toc != nil %} - {% assign toc = print-pdf-toc %} - {% elsif web-nav-tree != nil %} - {% assign toc = web-nav-tree %} - {% else %} - {% assign use-files-for-toc = true %} - {% endif %} - - {% elsif site.output == "screen-pdf" %} - {% if screen-pdf-toc != nil %} - {% assign toc = screen-pdf-toc %} - {% elsif print-pdf-toc != nil %} - {% assign toc = print-pdf-toc %} - {% elsif web-nav-tree != nil %} - {% assign toc = web-nav-tree %} - {% else %} - {% assign use-files-for-toc = true %} - {% endif %} - - {% elsif site.output == "epub" %} - {% if epub-toc != nil %} - {% assign toc = epub-toc %} - {% elsif print-pdf-toc != nil %} - {% assign toc = print-pdf-toc %} - {% elsif web-nav-tree != nil %} - {% assign toc = web-nav-tree %} - {% else %} - {% assign use-files-for-toc = true %} - {% endif %} - - {% elsif site.output == "web" %} - {% if web-toc != nil %} - {% assign toc = web-toc %} - {% elsif web-nav-tree != nil %} - {% assign toc = web-nav-tree %} - {% elsif print-pdf-toc != nil %} - {% assign toc = print-pdf-toc %} - {% else %} - {% assign use-files-for-toc = true %} - {% endif %} - - {% elsif site.output == "app" %} - {% if app-toc != nil %} - {% assign toc = app-toc %} - {% elsif app-nav-tree != nil %} - {% assign toc = app-nav-tree %} - {% elsif web-toc != nil %} - {% assign toc = web-toc %} - {% elsif web-nav-tree != nil %} - {% assign toc = web-nav-tree %} - {% elsif print-pdf-toc != nil %} - {% assign toc = print-pdf-toc %} - {% else %} - {% assign use-files-for-toc = true %} - {% endif %} - - {% else %} - {% if web-nav-tree != nil %} - {% assign toc = web-nav-tree %} - {% elsif print-pdf-toc != nil %} - {% assign toc = print-pdf-toc %} - {% else %} - {% assign use-files-for-toc = true %} - {% endif %} - - {% endif %} - -{% endunless %} - -{% comment %} Are we using files to generate a TOC, or -are we using the TOC defined in _data/works YAML? {% endcomment %} -{% if use-files-for-toc == true %} - -{% include nav-list-files.html type="toc" %} - -{% else %} - -{% comment %} -If the file that called this include didn't specify a start parameter, then -it must be the calling entire toc from the top. If so, then -we want the toc-branch to include the entire site.output-specific toc defined above. -Otherwise, the toc-branch should be the children called by this include recursively. -{% endcomment %} - -{% assign toc-branch = include.start %} - -{% if toc-branch == nil %} - {% assign toc-branch = toc %} -{% endif %} - -{% comment %}If we're not inside a book, we need a path to each file. -By default, assume we're linking to files in 'book', -and allow setting a different book directory as a 'book' argument.{% endcomment %} -{% if is-book-directory %} - {% capture toc-path-to-file %}{% endcapture %} -{% else %} - {% if include.book %} - {% capture toc-path-to-file %}{{ include.book }}/{% endcapture %} - {% else %} - {% capture toc-path-to-file %}book/{% endcapture %} - {% endif %} -{% endif %} - - -{% comment %} -Now we'll use all that to output the toc list. -{% endcomment %} - -{% comment %}If we're making an epub, and we're starting -at the top of the toc, put this in a nav element.{% endcomment %} -{% if site.output == "epub" and toc-branch == epub-toc or toc-branch == print-pdf-toc or toc-branch == web-nav-tree %} - -{% endif %} - -{% endif %} -{% comment %} if use-files-for-toc {% endcomment %} +
        diff --git a/_includes/toc-metadata b/_includes/toc-metadata new file mode 100644 index 00000000..8c1a1778 --- /dev/null +++ b/_includes/toc-metadata @@ -0,0 +1,173 @@ +{% comment %} +Get the file metadata. +{% endcomment %} +{% include metadata %} + +{% comment %} +Now check which output format we're creating, and capture its toc. +Fall back to print-pdf toc, then web nav list. +{% endcomment %} + +{% comment %} Create a flag for when there is +no toc in _data/works YAML. {% endcomment %} +{% assign use-files-for-toc = false %} + +{% unless include.start %} + + {% if site.output == "print-pdf" %} + {% if print-pdf-toc != nil %} + {% assign toc = print-pdf-toc %} + {% elsif web-nav-tree != nil %} + {% assign toc = web-nav-tree %} + {% else %} + {% assign use-files-for-toc = true %} + {% endif %} + + {% elsif site.output == "screen-pdf" %} + {% if screen-pdf-toc != nil %} + {% assign toc = screen-pdf-toc %} + {% elsif print-pdf-toc != nil %} + {% assign toc = print-pdf-toc %} + {% elsif web-nav-tree != nil %} + {% assign toc = web-nav-tree %} + {% else %} + {% assign use-files-for-toc = true %} + {% endif %} + + {% elsif site.output == "epub" %} + {% if epub-toc != nil %} + {% assign toc = epub-toc %} + {% elsif print-pdf-toc != nil %} + {% assign toc = print-pdf-toc %} + {% elsif web-nav-tree != nil %} + {% assign toc = web-nav-tree %} + {% else %} + {% assign use-files-for-toc = true %} + {% endif %} + + {% elsif site.output == "web" %} + {% if web-toc != nil %} + {% assign toc = web-toc %} + {% elsif web-nav-tree != nil %} + {% assign toc = web-nav-tree %} + {% elsif print-pdf-toc != nil %} + {% assign toc = print-pdf-toc %} + {% else %} + {% assign use-files-for-toc = true %} + {% endif %} + + {% elsif site.output == "app" %} + {% if app-toc != nil %} + {% assign toc = app-toc %} + {% elsif app-nav-tree != nil %} + {% assign toc = app-nav-tree %} + {% elsif web-toc != nil %} + {% assign toc = web-toc %} + {% elsif web-nav-tree != nil %} + {% assign toc = web-nav-tree %} + {% elsif print-pdf-toc != nil %} + {% assign toc = print-pdf-toc %} + {% else %} + {% assign use-files-for-toc = true %} + {% endif %} + + {% else %} + {% if web-nav-tree != nil %} + {% assign toc = web-nav-tree %} + {% elsif print-pdf-toc != nil %} + {% assign toc = print-pdf-toc %} + {% else %} + {% assign use-files-for-toc = true %} + {% endif %} + + {% endif %} + +{% endunless %} + +{% comment %} Are we using files to generate a TOC, or +are we using the TOC defined in _data/works YAML? {% endcomment %} +{% if use-files-for-toc == true %} + +{% include nav-list-files.html type="toc" %} + +{% else %} + +{% comment %} +If the file that called this include didn't specify a start parameter, then +it must be the calling entire toc from the top. If so, then +we want the toc-branch to include the entire site.output-specific toc defined above. +Otherwise, the toc-branch should be the children called by this include recursively. +{% endcomment %} + +{% assign toc-branch = include.start %} + +{% if toc-branch == nil %} + {% assign toc-branch = toc %} +{% endif %} + +{% comment %}If we're not inside a book, we need a path to each file. +By default, assume we're linking to files in 'book', +and allow setting a different book directory as a 'book' argument.{% endcomment %} +{% if is-book-directory %} + {% capture toc-path-to-file %}{% endcapture %} +{% else %} + {% if include.book %} + {% capture toc-path-to-file %}{{ include.book }}/{% endcapture %} + {% else %} + {% capture toc-path-to-file %}book/{% endcapture %} + {% endif %} +{% endif %} + + +{% comment %} +Now we'll use all that to output the toc list. +{% endcomment %} + +{% comment %}If we're making an epub, and we're starting +at the top of the toc, put this in a nav element.{% endcomment %} +{% if site.output == "epub" and toc-branch == epub-toc or toc-branch == print-pdf-toc or toc-branch == web-nav-tree %} + +{% endif %} + +{% endif %} +{% comment %} if use-files-for-toc {% endcomment %} diff --git a/_sass/template/partials/_pdf-tables.scss b/_sass/template/partials/_pdf-tables.scss index aad8a339..6cef27d2 100644 --- a/_sass/template/partials/_pdf-tables.scss +++ b/_sass/template/partials/_pdf-tables.scss @@ -10,6 +10,64 @@ $pdf-tables: true !default; width: 100%; max-width: $page-width - $margin-inside - $margin-outside; } + + .table { + clear: both; + margin: $line-height-default 0 0 0; + font-size: $font-size-table !important; + padding: 0; + width: 100%; + page-break-inside: avoid; + box-sizing: border-box; + background-color: inherit; + font-family: $font-text-secondary; + font-size: inherit; + font-weight: inherit; + color: inherit; + + .table-body { + + p { + clear: both; + page-break-inside: avoid; + page-break-before: avoid; + text-align: left; + text-indent: 0; + hyphens: none; + + // We avoid using these variables in outputs like web + // where font sizes are set in ems (i.e. proportionally). + // But here where we set font sizes in absolute units (pt) + // it's safe and useful to control font size in this way. + font-size: $font-size-default * $font-size-smaller; + } + + .table-images { + text-align: center; + margin-bottom: $line-height-default; + padding-bottom: $line-height-default; + } + + .table-html, .table-md {} + + .title {} + + // Descriptions are hidden by default, and used for image alt text + .description { + display: none; + } + + .caption { + page-break-after: avoid; + margin: 0; + text-align: left; + text-indent: 0; + .table-reference { + font-weight: bold; + } + } + } + } thead, th, .table-subhead { font-weight: bold; page-break-after: avoid; diff --git a/_sass/theme/partials/_print-figures-tables.scss b/_sass/theme/partials/_print-figures-tables.scss index 96aae3c1..9bd88ae4 100644 --- a/_sass/theme/partials/_print-figures-tables.scss +++ b/_sass/theme/partials/_print-figures-tables.scss @@ -39,4 +39,23 @@ th, td { th { text-align: center; -} \ No newline at end of file +} + +.table .table-body { + margin-bottom: 1.5 * $line-height-default; + + .caption { + font-family: $font-text-secondary; + font-weight: bold; + font-size: $font-size-default; + text-align: center; + + .table-reference::after { + content: "—"; + } + } + + .table-images { + margin-bottom: 0; + } +} diff --git a/_sass/theme/partials/_print-list-of-figures.scss b/_sass/theme/partials/_print-list-of-figures.scss new file mode 100644 index 00000000..8058a73d --- /dev/null +++ b/_sass/theme/partials/_print-list-of-figures.scss @@ -0,0 +1,73 @@ +// list-of-figures + +.contents-page { + .content > .list-of-figures > .figure-entry-title { + margin-top: $line-height-default; + } + .content > .list-of-figures > li { + margin: 0!important; + } + li { + a { + text-decoration: none!important; + color: inherit!important; + .figure-entry-text { + display: inline; + max-width: 90%; + } + .figure-reference::after { + content: '\2014'; // add emdash after reference + } + } + a::after { + content: leader(".") " " target-counter(attr(href), page); + } + a.frontmatter-reference::after { + content: leader(".") " " target-counter(attr(href), page, $frontmatter-reference-style); + } + &.frontmatter-entry, &.frontmatter-reference { + a::after { + content: leader(".") " " target-counter(attr(href), page, $frontmatter-reference-style); + } + } + } +} + +// PAGEDJS +.contents-page[data-pdf-engine="pagedjs"] { + .content > .list-of-figures > .figure-entry-title { + margin-top: $line-height-default; + } + + ol { + padding-left: 0; + } + + li { + a { + display: grid; + grid-template-columns: 100%; + + span.figure-entry-text { + grid-column: 1 / 2; + grid-row: 1 / 2; + justify-self: start; + background-color: white; + z-index: 4; + + &::after { + content: ' '; + padding-left: 0.5em; + background-color: white; + } + } + } + + a::after { + content: '............................................................................................................................................................ ' target-counter(attr(href), page); + grid-column: 1 / 2; + grid-row: 1 / 2; + justify-self: end; + } + } +} diff --git a/_sass/theme/partials/_print-list-of-tables.scss b/_sass/theme/partials/_print-list-of-tables.scss new file mode 100644 index 00000000..147f2340 --- /dev/null +++ b/_sass/theme/partials/_print-list-of-tables.scss @@ -0,0 +1,73 @@ +// list-of-tables + +.contents-page { + .content > .list-of-tables > .table-entry-title { + margin-top: $line-height-default; + } + .content > .list-of-tables > li { + margin: 0!important; + } + li { + a { + text-decoration: none!important; + color: inherit!important; + .table-entry-text { + display: inline; + max-width: 90%; + } + .table-reference::after { + content: '\2014'; // add emdash after reference + } + } + a::after { + content: leader(".") " " target-counter(attr(href), page); + } + a.frontmatter-reference::after { + content: leader(".") " " target-counter(attr(href), page, $frontmatter-reference-style); + } + &.frontmatter-entry, &.frontmatter-reference { + a::after { + content: leader(".") " " target-counter(attr(href), page, $frontmatter-reference-style); + } + } + } +} + +// PAGEDJS +.contents-page[data-pdf-engine="pagedjs"] { + .content > .list-of-tables > .table-entry-title { + margin-top: $line-height-default; + } + + ol { + padding-left: 0; + } + + li { + a { + display: grid; + grid-template-columns: 100%; + + span.table-entry-text { + grid-column: 1 / 2; + grid-row: 1 / 2; + justify-self: start; + background-color: white; + z-index: 4; + + &::after { + content: ' '; + padding-left: 0.5em; + background-color: white; + } + } + } + + a::after { + content: '............................................................................................................................................................ ' target-counter(attr(href), page); + grid-column: 1 / 2; + grid-row: 1 / 2; + justify-self: end; + } + } +} diff --git a/_sass/theme/pdf-rules.scss b/_sass/theme/pdf-rules.scss index 209b76f6..1fc4998a 100644 --- a/_sass/theme/pdf-rules.scss +++ b/_sass/theme/pdf-rules.scss @@ -10,5 +10,7 @@ @import "theme/partials/print-notes"; @import "theme/partials/print-pdf-view"; @import "theme/partials/print-toc"; +@import "theme/partials/print-list-of-figures"; +@import "theme/partials/print-list-of-tables"; @import "theme/partials/print-typography"; @import "theme/partials/print-helpers"; diff --git a/_tools/run/helpers/helpers.js b/_tools/run/helpers/helpers.js index 4239c47a..17de5fd3 100644 --- a/_tools/run/helpers/helpers.js +++ b/_tools/run/helpers/helpers.js @@ -604,6 +604,8 @@ async function convertXHTMLFiles (argv) { async function renderNumbering (argv) { 'use strict' + if (argv['section-numbering'] == -1) return; // skip when disabled + const fileNames = markdownFilePaths(argv); await numberSections(argv, fileNames, {}); } @@ -1751,6 +1753,7 @@ module.exports = { openOutputFile, outputTOC, pathExists, + projectSettings, processImages, refreshIndexes, renderIndexComments, diff --git a/_tools/run/helpers/merge/index.js b/_tools/run/helpers/merge/index.js index 2283b8dc..417afe65 100644 --- a/_tools/run/helpers/merge/index.js +++ b/_tools/run/helpers/merge/index.js @@ -6,14 +6,16 @@ const { JSDOM } = jsdom const fs = require('fs-extra') const fsPath = require('path') const fsPromises = require('fs/promises') +const buildTocNav = require('../reindex/build-toc-nav.js') // Local helpers const htmlFilePaths = require('../helpers').htmlFilePaths +const projectSettings = require('../helpers').projectSettings // Make IDs in HTML unique by prefixing them // with the slug of the filename, and updating // any links that point to them. -function updateIDs (filename, dom, argv) { +function updateIDs(filename, dom, argv) { return new Promise(function (resolve, reject) { try { // Prefix IDs with a no-spaces, no-fullstops filename @@ -46,8 +48,8 @@ function updateIDs (filename, dom, argv) { internalLinks = linksArray.filter(function (link) { let isInternal = true if (link.href.startsWith('https://') || - link.href.startsWith('mailto:') || - link.href.startsWith('http://')) { + link.href.startsWith('mailto:') || + link.href.startsWith('http://')) { isInternal = false } return isInternal @@ -68,9 +70,10 @@ function updateIDs (filename, dom, argv) { // and only keep the filename. // If it's to another book, we must leave the link as is, // and set a flag that prevents us from changing it later. + // MB: In case the href contains a starting slash, we need to remove the empty array element let hrefIsToThisBook = true if (href.match(/\//)) { - const hrefAsArray = href.replace(/^\.\.\//, '').split('/') + const hrefAsArray = href.replace(/^\.\.\//, '').split('/').filter(i => i != '') if (hrefAsArray[0] === argv.book) { href = hrefAsArray.pop() } else { @@ -113,21 +116,122 @@ function updateIDs (filename, dom, argv) { }) } +function getToCItems(items, dom, parent) { + items.forEach(item => { + if (item && item.chapterOrAnnex) { // skip items that are not Chapter or Annex + let listElement = dom.window.document.createElement('li'); + listElement.className = "toc-entry-title"; + let refElement = dom.window.document.createElement('a'); + refElement.href = '#' + item.id; + let spanElement = dom.window.document.createElement("span"); + spanElement.className = "toc-entry-text" + spanElement.innerHTML = item.label.replace(/(<\/?strong>)/gi, "").replace(/(<\/?b>)/gi, ""); // remove strong/bold + refElement.appendChild(spanElement); + listElement.appendChild(refElement); + if (item.children && item.children.length) { + let olistElement = dom.window.document.createElement('ol'); + olistElement.className = "toc-list"; + listElement.appendChild(olistElement); + getToCItems(item.children, dom, olistElement); + } + parent.appendChild(listElement); + } + }); +} + +function updateToC(data, dom) { + const outputList = data.reduce((arr, { level, ...rest }) => { + const value = { ...rest, children: [] } + arr[level] = value.children + let parent = arr[level - 1] ? arr[level - 1] : + arr[level - 2] ? arr[level - 2] : + arr[level - 3] ? arr[level - 3] : + arr[level - 4] ? arr[level - 4] : null; // in case parent does not exist, check parent of parent, up to 4 levels up + if (parent) { parent.push(value) } + return arr + }, [[]]).shift(); + let tocElements = dom.window.document.getElementsByClassName('toc-list-auto'); + let tocElement = tocElements[tocElements.length - 1]; // get last element + if (!tocElement) return; // no toc-list-auto placeholder found, so no need to autogenerate ToC + console.log('Embedding ToC...') + getToCItems(outputList, dom, tocElement); +} + +function extractHeaders(dom, argv) { + let headerElements = []; + const headingLevels = projectSettings()[argv.format].toc['heading-levels']; + const allHeadings = dom.window.document.querySelectorAll(headingLevels.join(', ')); + + allHeadings.forEach(item => { + if (!item.classList.contains('no-toc')) { + const inChapterOrAnnex = item.closest('.chapter') || item.closest('.annex'); // check if we are in Chapter or Annex + headerElements.push({ + id: item.id, + label: item.innerHTML, + level: parseInt(item.nodeName[1]), + chapterOrAnnex: inChapterOrAnnex ? true : false + }); + } + }); + return headerElements; +} + +function createListOfFigures(dom) { + let parent = dom.window.document.getElementsByClassName('list-of-figures')[0]; // first element + const collection = [...dom.window.document.getElementsByClassName('figure')]; + if (parent && collection.length) { + collection.forEach(item => { + let listElement = dom.window.document.createElement('li'); + listElement.className = "figure-entry-title"; + let refElement = dom.window.document.createElement('a'); + let id = item.id + '-caption'; + refElement.href = '#' + id; + let spanElement = dom.window.document.createElement("span"); + spanElement.className = "figure-entry-text" + spanElement.innerHTML = dom.window.document.getElementById(id).innerHTML; + refElement.appendChild(spanElement); + listElement.appendChild(refElement); + parent.appendChild(listElement); + }); + } +} + +function createListOfTables(dom) { + let parent = dom.window.document.getElementsByClassName('list-of-tables')[0]; // first element + const collection = [...dom.window.document.getElementsByClassName('table')]; + if (parent && collection.length) { + collection.forEach(item => { + let listElement = dom.window.document.createElement('li'); + listElement.className = "table-entry-title"; + let refElement = dom.window.document.createElement('a'); + let id = item.id + '-caption'; + refElement.href = '#' + id; + let spanElement = dom.window.document.createElement("span"); + spanElement.className = "table-entry-text" + spanElement.innerHTML = dom.window.document.getElementById(id).innerHTML; + refElement.appendChild(spanElement); + listElement.appendChild(refElement); + parent.appendChild(listElement); + }); + } +} + // Merge source HTML files into a single file -async function merge (argv) { +async function merge(argv) { // Don't merge files if --merged has not // been passed at the command line if (argv.merged === false) { return } - console.log('Merging HTML files ...') + console.log('Merging HTML files...') return new Promise(function (resolve, reject) { try { const filePaths = htmlFilePaths(argv) let fileCounter = 1 let mergedDom + let tocEntries = []; const destination = fsPath.dirname(filePaths[0]) + '/merged.html' filePaths.forEach(async function (filePath) { @@ -138,6 +242,12 @@ async function merge (argv) { const filename = fsPath.basename(filePath) dom = await updateIDs(filename, dom, argv) + // extract headers + const headers = extractHeaders(dom, argv); + if (headers.length) { + tocEntries = [...tocEntries, ...headers]; + } + // If this is the first file, we'll use it as our base, // to which we'll append the remaining files. if (fileCounter === 1) { @@ -155,6 +265,11 @@ async function merge (argv) { // If this is not the last file, remove the script tag // that loads bundle.js, so it doesn't load multiple times. if (fileCounter === filePaths.length) { + updateToC(tocEntries, mergedDom); + + createListOfFigures(mergedDom); + createListOfTables(mergedDom); + console.log('Writing merged HTML to ' + destination) fsPromises.writeFile(destination, mergedDom.serialize()) resolve(true) diff --git a/_tools/run/helpers/numbering/index.js b/_tools/run/helpers/numbering/index.js index a698997f..21813ca6 100644 --- a/_tools/run/helpers/numbering/index.js +++ b/_tools/run/helpers/numbering/index.js @@ -7,10 +7,13 @@ const { ebSlugify } = require('../../../gulp/helpers/utilities.js'); async function numberSections(argv, files) { this.isChapter = false; + this.inCodeBlock = false; + this.inRawBlock = false; + this.inCommentBlock = false; this.annexLevel = 0; this.topicName = []; this.override = argv.override; - this.numberingDepth = (argv['section-numbering'] > 0 && argv['section-numbering'] < 6) ? argv['section-numbering'] : 5; + this.numberingDepth = (argv['section-numbering'] > -1 && argv['section-numbering'] < 6) ? argv['section-numbering'] : 5; this.section = {}; this.figureNumber = 0; this.tableNumber = 0; @@ -138,7 +141,7 @@ async function numberSections(argv, files) { // required for figures for await (const line of lineReader) { block += line + '\n'; - if (line == '') { + if (line.replace(' ','') == '') { // make sure we detect 'empty lines' which only contain spaces const updatedBlock = updateBlock(block, updateXref); writeStream.write(updatedBlock); block = ''; @@ -148,17 +151,20 @@ async function numberSections(argv, files) { return waitForStreamClose(writeStream); } - function updateBlock (block, updateXref) { + function updateBlock(block, updateXref) { const section = block.match(/^#+/); const chapter = block.match(/style: chapter/); const annex = block.match(/style: annex/); const xref = [...block.matchAll(/(\[[0-9a-zA-Z\s.\-]+\]|\[\])\((([^\s^\)]+)?)\)/gi)]; - const codeblock = block.match(/^\`\`\`/); - const rawblock = block.match(/^\{\%\s+raw\s+\%\}/); + const codeblockStart = block.match(/^\`{3}/); + const codeblockEnd = block.match(/\`{3}\n\n$/); + const rawblockStart = block.match(/^\{\%\s*raw\s*\%\}/); + const rawblockEnd = block.match(/\{\%\s*endraw\s*\%\}\n\n/); + const commentblockStart = block.match(/^\{\%\s*comment\s*\%\}/); + const commentblockEnd = block.match(/\{\%\s*endcomment\s*\%\}\n\n/); const table = block.match(/^\{\%\s+include\s+table/); const figure = block.match(/^\{\%\s+include\s+figure/); const equation = block.match(/^\{\%\s+include\s+equation/); - if (xref.length && updateXref) { return updateCrossReference(xref, block); } @@ -167,14 +173,21 @@ async function numberSections(argv, files) { return block; } - // no not process codeblocks, rawblocks - if (codeblock || rawblock) { - return block; + if(codeblockStart && !codeblockEnd) { + this.inCodeBlock = true; + } + + if(rawblockStart && !rawblockEnd) { + this.inRawBlock = true; + } + + if(commentblockStart && !commentblockEnd) { + this.inCommentBlock = true; } if (chapter) { this.isChapter = true; - this.annexLevel=0; + this.annexLevel = 0; } if (annex) { @@ -186,23 +199,35 @@ async function numberSections(argv, files) { this.figureNumber = 0; } - if (section && (this.isChapter || this.annexLevel>0)) { + if (section && (this.isChapter || this.annexLevel>0) && !this.inCodeBlock && !this.inRawBlock && !this.inCommentBlock) { level = section[0].length; return updateSectionNumber(block, level); } - if (table) { + if (table && !this.inCodeBlock && !this.inRawBlock && !this.inCommentBlock) { return updateTableReference(block); } - if (figure) { + if (figure && !this.inCodeBlock && !this.inRawBlock && !this.inCommentBlock) { return updateFigureReference(block); } - if (equation) { + if (equation && !this.inCodeBlock && !this.inRawBlock && !this.inCommentBlock) { return updateEquationReference(block); } + if (codeblockEnd) { + this.inCodeBlock = false; + } + + if(rawblockEnd) { + this.inRawBlock = false; + } + + if(commentblockEnd) { + this.inCommentBlock = false; + } + return block; // no change if no other match found } diff --git a/_tools/run/helpers/options.js b/_tools/run/helpers/options.js index 2265013d..66baac0a 100644 --- a/_tools/run/helpers/options.js +++ b/_tools/run/helpers/options.js @@ -128,7 +128,7 @@ const options = { 'section-numbering': { description: 'Depth of section (re)numbering in the book', alias: 's', - default: 0, + default: -1, defaultDescription: '0', type: 'number' }, diff --git a/_tools/run/helpers/output/index.js b/_tools/run/helpers/output/index.js index f6723b68..3286885a 100644 --- a/_tools/run/helpers/output/index.js +++ b/_tools/run/helpers/output/index.js @@ -30,15 +30,23 @@ const { } = require('../helpers.js') const merge = require('../merge') +async function copyBooks(argv, from, to, removeDir=false) { + await fs.emptyDir(process.cwd() + to + argv.book); + // first copy source files in books to root folder + // such that jekyll finds them + fs.copySync(process.cwd() + from + argv.book, process.cwd() + to + argv.book); + if (removeDir) { + fs.removeSync(process.cwd() + from + argv.book); + } +} + // Web output async function web (argv) { 'use strict' try { await fs.emptyDir(process.cwd() + '/_site') - if (argv['section-numbering'] > 0) { - await renderNumbering(argv) - } + await renderNumbering(argv) await jekyll(argv) } catch (error) { console.log(error) @@ -51,13 +59,14 @@ async function pdf (argv) { try { await fs.emptyDir(process.cwd() + '/_site') - if (argv['section-numbering'] > 0) { - await renderNumbering(argv) - } + await copyBooks(argv, '/books/','/'); + await renderNumbering(argv) await jekyll(argv) await renderIndexComments(argv) await renderIndexLinks(argv) await merge(argv) + await copyBooks(argv, '/','/_output/update/', true); + await copyBooks(argv, '/_site/','/_output/html/'); await renderMathjax(argv) if (argv['pdf-engine'] === 'pagedjs') { await runPagedJS(argv) @@ -76,9 +85,7 @@ async function epub (argv) { try { await fs.emptyDir(process.cwd() + '/_site') - if (argv['section-numbering'] > 0) { - await renderNumbering(argv) - } + await renderNumbering(argv) await jekyll(argv) await epubHTMLTransformations(argv) await renderIndexComments(argv) @@ -169,9 +176,7 @@ async function app (argv) { try { await fs.emptyDir(process.cwd() + '/_site') - if (argv['section-numbering'] > 0) { - await renderNumbering(argv) - } + await renderNumbering(argv) await jekyll(argv) await fsPromises.mkdir(process.cwd() + '/_site/app/www') await assembleApp() diff --git a/_tools/run/helpers/reindex/build-toc-nav.js b/_tools/run/helpers/reindex/build-toc-nav.js index fbda8ea3..92e08d21 100644 --- a/_tools/run/helpers/reindex/build-toc-nav.js +++ b/_tools/run/helpers/reindex/build-toc-nav.js @@ -5,7 +5,7 @@ const fsPromises = require('fs/promises') const yaml = require('js-yaml') // The main process for generating TOC YAML -async function buildTocNav (outputFormat, headingLevels) { +async function buildTocNav(outputFormat, headingLevels) { 'use strict' const tocObj = { @@ -106,7 +106,7 @@ async function buildTocNav (outputFormat, headingLevels) { // Create empty output file to write to, if it doesn't exist const outputFilePath = fsPath.normalize(process.cwd() + - '/_output/toc.yml') + '/_output/toc.yml') if (!fs.existsSync(outputFilePath)) { console.log('Creating ' + outputFilePath) await fsPromises.writeFile(outputFilePath, '') @@ -128,7 +128,7 @@ async function buildTocNav (outputFormat, headingLevels) { console.log('File written successfully') } } - ) + ); } // Run the rendering process. diff --git a/accellera-standard-template/0-0-titlepage.md b/accellera-standard-template/0-0-titlepage.md deleted file mode 100644 index 750e669d..00000000 --- a/accellera-standard-template/0-0-titlepage.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -style: title-page ---- - -{% include title-page %} diff --git a/accellera-standard-template/0-1-abstract.md b/accellera-standard-template/0-1-abstract.md deleted file mode 100644 index ace5bd06..00000000 --- a/accellera-standard-template/0-1-abstract.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -style: frontmatter ---- -{% include metadata %} - -**Abstract**: {{ description }} - -**Keywords**: {{ keywords }} diff --git a/accellera-standard-template/0-2-notice.md b/accellera-standard-template/0-2-notice.md deleted file mode 100644 index f7f080d4..00000000 --- a/accellera-standard-template/0-2-notice.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -style: frontmatter ---- - -# Notices - -**Accellera Systems Initiative (Accellera) Standards** documents are developed within Accellera and the Technical Committee of Accellera. Accellera develops its standards through a consensus development process, approved by its members and board of directors, which brings together volunteers representing varied viewpoints and interests to achieve the final product. Volunteers are members of Accellera and serve without compensation. While Accellera administers the process and establishes rules to promote fairness in the consensus development process, Accellera does not independently evaluate, test, or verify the accuracy of any of the information contained in its standards. - -Use of an Accellera Standard is wholly voluntary. Accellera disclaims liability for any personal injury, property or other damage, of any nature whatsoever, whether special, indirect, consequential, or compensatory, directly or indirectly resulting from the publication, use of, or reliance upon this, or any other Accellera Standard document. - -Accellera does not warrant or represent the accuracy or content of the material contained herein, and expressly disclaims any express or implied warranty, including any implied warranty of merchantability or suitability for a specific purpose, or that the use of the material contained herein is free from patent infringement. Accellera Standards documents are supplied **“AS IS.”** - -The existence of an Accellera Standard does not imply that there are no other ways to produce, test, measure, purchase, market, or provide other goods and services related to the scope of an Accellera Standard. Furthermore, the viewpoint expressed at the time a standard is approved and issued is subject to change due to developments in the state of the art and comments received from users of the standard. Every Accellera Standard is subjected to review periodically for revision and update. Users are cautioned to check to determine that they have the latest edition of any Accellera Standard. - -In publishing and making this document available, Accellera is not suggesting or rendering professional or other services for, or on behalf of, any person or entity. Nor is Accellera undertaking to perform any duty owed by any other person or entity to another. Any person utilizing this, and any other Accellera Standards document, should rely upon the advice of a competent professional in determining the exercise of reasonable care in any given circumstances. - -Interpretations: Occasionally questions may arise regarding the meaning of portions of standards as they relate to specific applications. When the need for interpretations is brought to the attention of Accellera, Accellera will initiate action to prepare appropriate responses. Since Accellera Standards represent a consensus of concerned interests, it is important to ensure that any interpretation has also received the concurrence of a balance of interests. For this reason, Accellera and the members of its Technical Committees are not able to provide an instant response to interpretation requests except in those cases where the matter has previously received formal consideration. - -Comments for revision of Accellera Standards are welcome from any interested party, regardless of membership affiliation with Accellera. Suggestions for changes in documents should be in the form of a proposed change of text, together with appropriate supporting comments. Comments on standards and requests for interpretations should be addressed to: - -> Accellera Systems Initiative.\\ -> 8698 Elk Grove Blvd Suite 1, #114\\ -> Elk Grove, CA 95624\\ -> USA - -Note: Attention is called to the possibility that implementation of this standard may require use of subject matter covered by patent rights. By publication of this standard, no position is taken with respect to the existence or validity of any patent rights in connection therewith. Accellera shall not be responsible for identifying patents for which a license may be required by an Accellera standard or for conducting inquiries into the legal validity or scope of those patents that are brought to its attention. -{:.note} - -Accellera is the sole entity that may authorize the use of Accellera-owned certification marks and/or trademarks to indicate compliance with the materials set forth herein. - -Authorization to photocopy portions of any individual standard for internal or personal use must be granted by Accellera, provided that permission is obtained from and any required fee is paid to Accellera. To arrange for authorization please contact Lynn Garibaldi, Accellera Systems Initiative, 8698 Elk Grove Blvd Suite 1, #114, Elk Grove, CA 95624, phone (916) 670-1056, e-mail . Permission to photocopy portions of any individual standard for educational classroom use can also be obtained from Accellera. - -Suggestions for improvements to the *name* Standard are welcome. They should be posted to the *name* Community Forum at: - -> [https://forums.accellera.org/forum/forum-name/](https://forums.accellera.org/forum/forum-name/) - -The current Working Group web page is: - -> [http://www.accellera.org/activities/working-groups/working-group-name](http://www.accellera.org/activities/working-groups/working-group-name) diff --git a/accellera-standard-template/0-3-introduction.md b/accellera-standard-template/0-3-introduction.md deleted file mode 100644 index 990abb74..00000000 --- a/accellera-standard-template/0-3-introduction.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -style: frontmatter ---- - -# Introduction - -| This introduction is informative and not part of the [draft] [name] standard - -The introduction page is optional for Accellera standards and considered informative. It may be added to the standard to explain the context and history of the standard. In case the standard is integral part of family of associated standards, the relation to the other standards should be explained. - -# Acknowledgments - -In case the standard incorporates specific contributions of individuals or organizations, these can be listed and acknowledged here. diff --git a/accellera-standard-template/0-4-participants.md b/accellera-standard-template/0-4-participants.md deleted file mode 100644 index 32fbec10..00000000 --- a/accellera-standard-template/0-4-participants.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -style: frontmatter ---- - -# Participants - -At the time this Accellera standard was completed, the *name* Working Group had the following membership: - -| **AAA**, Chair -| **BBB**, Vice Chair -| **CCC**, Secretary -| **DDD**, Technical Editor -{:.table-no-border.table-no-padding.table-text-center} - -| Name 1 | Name 4 | Name 7 | -| Name 2 | Name 5 | Name 8 | -| Name 3 | Name 6 | Name 9 | -{:.table-no-border.table-no-padding.table-columns-fixed} - -The following members of the entity balloting committee voted on this standard. Balloters may have voted for approval, disapproval, or abstention. - -| Company 1 | Company 4 | Company 7 | -| Company 2 | Company 5 | Company 8 | -| Company 3 | Company 6 | Company 9 | -{:.table-no-border.table-no-padding.table-columns-fixed} diff --git a/accellera-standard-template/0-5-contents.md b/accellera-standard-template/0-5-contents.md deleted file mode 100644 index b1efcba6..00000000 --- a/accellera-standard-template/0-5-contents.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -style: contents-page ---- - -# Contents - -{% include toc %} diff --git a/accellera-standard-template/01.md b/accellera-standard-template/01.md deleted file mode 100644 index ab02f764..00000000 --- a/accellera-standard-template/01.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -style: chapter no-header ---- - -{% include metadata %} - -{{ title }} -{:.title} - -# 1. Overview - -## 1.1 Scope - -Describe the scope of the standard here. - -## 1.2 Purpose - -Describe the purpose of the standard here. - -## 1.3 Word usage - -The word *shall* indicates mandatory requirements strictly to be followed in order to conform to the standard and from which no deviation is permitted (*shall* equals *is required to*).[^fn1], [^fn2] - -The word *should* indicates that among several possibilities one is recommended as particularly suitable, without mentioning or excluding others; or that a certain course of action is preferred but not necessarily required (*should* equals *is recommended that*). - -The word *may* is used to indicate a course of action permissible within the limits of the standard (*may* equals *is permitted to*). - -The word *can* is used for statements of possibility and capability, whether material, physical, or causal (*can* equals *is able to*). - -[^fn1]: The use of the word *must* is deprecated and cannot be used when stating mandatory requirements; *must* is used only to describe unavoidable situations. -[^fn2]: The use of *will* is deprecated and cannot be used when stating mandatory requirements; *will* is only used in statements of fact. diff --git a/accellera-standard-template/02.md b/accellera-standard-template/02.md deleted file mode 100644 index 4b7ad7ac..00000000 --- a/accellera-standard-template/02.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -style: chapter ---- - -# 2. Normative references - -Add normative references here. - diff --git a/accellera-standard-template/03.md b/accellera-standard-template/03.md deleted file mode 100644 index 91c29403..00000000 --- a/accellera-standard-template/03.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -style: chapter ---- - -# 3. Definitions, acronyms, and abbreviations - -For the purposes of this document, the following terms and definitions apply. The IEEE Standards Dictionary Online should be consulted for terms not defined in this clause.[^fn3] - -## 3.1 Definitions - -Add definitions here. - -[^fn3]: IEEE Standards Dictionary Online is available at [https://ieeexplore.ieee.org](https://ieeexplore.ieee.org). diff --git a/accellera-standard-template/04.md b/accellera-standard-template/04.md deleted file mode 100644 index 5e6ca548..00000000 --- a/accellera-standard-template/04.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -style: chapter ---- - -# 4. Body of the standard - -The normative text of the standard starts here. - -Example of reference to [Clause 1](01.html) and reference to [3.1](03.html#31-definitions). - -{% comment %} -Inline comments for the author of the document -{% endcomment %} diff --git a/accellera-standard-template/a.md b/accellera-standard-template/a.md deleted file mode 100644 index a059ee8a..00000000 --- a/accellera-standard-template/a.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -style: annex ---- - -# Annex A **(informative)** Title - -Annex page template. diff --git a/accellera-style-guide/01.md b/accellera-style-guide/01.md deleted file mode 100644 index 5061674a..00000000 --- a/accellera-style-guide/01.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -style: chapter no-header ---- - -{% include metadata %} - -{{ title }} -{:.title} - -# 1. Overview - -## 1.1 Purpose - -This style guide defines the recommended structure, formatting and style to develop and deploy Accellera (Draft) Standards, User Guides and other standard-related documentation. - -This style guide is intended for Accellera working group members which are assigned as technical editor to author standard-related documentation. Technical editors are encouraged to contact the Accellera Technical Committee chair for additional guidance and support when developing a standard-related document. In the case of changes or deviations to the recommended formatting and style as defined in this guide, it is required to contact the Technical Committee chair for approval. Please note that deviations to the formatting and style may result in a delayed approval of the Accellera (draft) standard, or even difficulties to transfer an Accellera standard to the IEEE Standardization Association. As such - -This style guide is not addressing the policies and procedures for the development of Accellera standards. For that, please consult the [Accellera Policies & Procedures](https://www.accellera.org/images/about/policies/Policies_and_Procedures_2021.pdf) which can be found at the [Accellera](https://www.accellera.org/about/policies-and-procedures) website. - -## 1.2 Helpful resources - -The following documents are helpful resources for writing an Accellera standard-related document. - -[IEEE SA Standards Style Manual](https://mentor.ieee.org/myproject/Public/mytools/draft/styleman.pdf) - -[Electric Book documentation](https://electricbookworks.github.io/electric-book/docs/) - -[Kramdown Quick Reference](https://kramdown.gettalong.org/quickref.html) - -## 1.3 Using the Accellera documentation flow - -It is strongly recommended to use the Accellera documentation flow to develop Accellera standard documents. When using this flow, the required Accellera and/or IEEE formatting and styles are automatically applied as part of the PDF rendering flow. - -The documentation flow uses an Accellera-owned GitHub private account to store document sources. Each standard document will be stored in a separate repository under this GitHub account. Accellera working groups should contact the Technical Committee chair to request creation of such documentation repository. - -Each documentation repository contains the required installation scripts and automation to create, author and render documents. Technical editors should have access to a Linux machine with administrator (sudo) access to be able to install the required tool packages and scripts. It is recommended to create a Linux virtual machine (e.g., VirtualBox) for this activity. More information can be found in [Annex A](a.html). - -Please contact the Technical Committee chair in case of questions on the Accellera documentation flow, the required installation procedure or use of the standard document templates. diff --git a/accellera-style-guide/02.md b/accellera-style-guide/02.md deleted file mode 100644 index e89e1951..00000000 --- a/accellera-style-guide/02.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -style: chapter ---- - -# 2. Project setup - -This chapter explains the project setup and use of the GitHub repository for technical documentation. - -## 2.1 GitHub repository setup - -It is recommended to use a dedicated GitHub repository to develop a single standard book. Please contact the Technical Committee chair to request a new repository for the technical documentation. After this, a new GitHub repository is created, including the installation of default templates and scripts to generate an IEEE SA stylesheet compatible standards document. - -[Table 1](#table-1) below gives an overview of the default structure of the repository. - -{% include table - reference="Table 1" - caption="Repository structure" - class="fixed allow-break" - caption-position="top" - markdown=" -| Directory | Purpose / Content | Used by Technical editor(s) | -|----------------|----------------------------------------------|------------------------------| -| `_api/` | API to fetch metadata and content in JSON | No | -| `_app/` | Template files for app output | No | -| `_configs/` | Configuration settings for different outputs | No | -| `_data/` | Project (meta)data and settings e.g.,
        `settings.yml`, `locales.yml` | No | -| `_data/works/accellera-standard-template/` | Metadata of the Accellera standards template in YAML (`default.yml`) | Yes | -| `_data/works/accellera-style-guide/` | Metadata of the Accellera Style Guide in YAML (`default.yml`) | No | -| `_data/works/ieee-sa-standards-style-manual/` | Metadata of the IEEE SA Standards Style Manual template in YAML (`default.yml`) | No | -| `_doc/` | This documentation | No | -| `_epub/` | Template files for epub output | No | -| `_includes/` | HTML templates to render the document | No | -| `_layouts/` | Templates to structure pages | No | -| `_output/` | Output directory for PDFs and epubs | Yes | -| `_sass/` | Location to store default document styles | No | -| `_site/` | Directory for web and app versions of the document | No | -| `_tools/` | Flow documentation utilities | No | -| `accellera-standard-template/` | Directory containing the Accellera standard template | Yes | -| `accellera-style-guide/` | Directory containing the Accellera Style Guide | No | -| `assets/` | Styles and images for the project | No | -| `ieee-sa-standards-style-manual/` | Directory containing the IEEE SA Standards Style Manual | No | -" -%} - -In addition, the root directory also contains some configuration settings to enable flow installation, automation and/or deployment. Normally technical editor(s) do not have to change these files. - -## 2.2 Accellera standard template - -The directory containing the Accellera standard template is called `accellera-standard-template`. This directory will contain the document source files in Markdown format, as well as the default images and stylesheets. The metadata for the Accellera standard template is located in directory `_data/works/accellera-standard-template/`. - -[Table 2](#table-2) gives an overview of the relevant directories. - -{% include table - reference="Table 2" - caption="Standard document subdirectory structure" - class="fixed allow-break" - caption-position="top" - markdown=" -| File / directory | Purpose / Content | -|------------------------------------|--------------------------| -| `_data/works/accellera-standard-template/default.yml` | Metadata of the document | -| `accellera-standard-template/images/` | Location to store images | -| `accellera-standard-template/styles/` | Location for stylesheets | -| `accellera-standard-template/index.md` | Landing page (e.g. cover) for the standard document | -| `accellera-standard-template/package.opf` | Placeholder to generate epub output (do not edit or remove) | -| `accellera-standard-template/toc.ncx` | Placeholder to generate navigation file for old ereaders (do not edit or remove) | -" -%} - -When starting with the technical editing of a new standard, it is recommended to copy the template and metadata directories to new directories reflecting the name of the new standard document. - - -## 2.3 Tool setup - -[Annex A](a.html) explains the installation of a virtual machine, the Xubuntu operating system, and the packages required to publish documents. - -Note that this tool setup is only required for the publication of standard documents, which is the responsibility of the technical editor. For document editing and authoring, access to the GitHub project and availability of a simple ASCII editor is sufficient. diff --git a/accellera-style-guide/a.md b/accellera-style-guide/a.md deleted file mode 100644 index c8543c19..00000000 --- a/accellera-style-guide/a.md +++ /dev/null @@ -1,116 +0,0 @@ ---- -style: annex ---- - -# Annex A **(informative)** Environment setup - -## A.1 Download VirtualBox - -Visit the VirtualBox website [here][virtualbox] to download the binary for your current host operating system. When using Windows as host operating system, download the platform package for **Windows hosts**. Other platform packages are also available, such as Linux and macOS. After download is completed, install VirtualBox with the defaults settings. - -## A.2 Download Ubuntu ISO image - -As guest operating system, Linux will be used. In this setup, Xubuntu is selected, an Ubuntu distribution using Xfce as window manager and desktop environment. Alternative linux distributions can use used, as long as they are supporting the Debian package management infrastructure (e.g. `apt`). Download the Xubuntu 22.04.4 64-bit ISO image [here][xubuntu]. - -## A.3 Create a virtual machine - -Open VirtualBox and click on the blue **New** button. It will open a dialog box to specify the creation of a virtual machine, see image below. - -{% include figure - reference="Figure A.1" - caption="Create virtual machine" - alt-text="" - class="fixed" - images="create_vm.png" -%} - -Enter the following information into the fields. Note: replace <user> with your user account. -- Name: Xubuntu 22.04.4 EBW environment -- Folder: C:\Users\<user>\VirtualBox VMs -- ISO image: C:\Users\<user>\Downloads\xubuntu-22.04.4-desktop-amd64.iso - -Click on **Next** to specify the account details, see figure below. In this setup, a new account `accellera` is created. Specify the strong password. Optional is to specify a hostname (e.g., `ebw`) and domain name (e.g., `ebw.virtualbox.org`). Also enable the box *Guest Additions*. After completion, click on **Next**. - -{% include figure - reference="Figure A.2" - caption="Account username and password (hostname and domain name are optional)" - alt-text="" - class="fixed" - images="vm_account.png" -%} - -Specify the memory size and number of processors for the virtual machine, as shown below. There is no need to thick the box *Enable EFI*. After completion, click on **Next**. - -{% include figure - reference="Figure A.3" - caption="Virtual machine memory and processors" - alt-text="" - class="fixed" - images="vm_hardware.png" -%} - -Next, specify the available disk space for the virtual machine, see figure below. It is recommended to define a partition bigger than 10 GB. After completion, click on **Next**. - -{% include figure - reference="Figure A.4" - caption="Virtual machine disk space" - alt-text="" - class="fixed" - images="vm_disk.png" -%} - -The next dialog presents a summary. Check all settings, and in case a change is required, use the **Back** button to update the configuration. If all settings are correct, click **Finish**. - -## A.4 Install Xubuntu - -The virtual machine starts and installs Xubuntu. Depending on the available resources on your host operating system, installation will take between 10 and 20 minutes. After installation the virtual machine will reboot and shows the login screen. Enter the specified password to login. - -To enable sharing of clipboard content between the host OS and virtual machine, use the VirtualBox menu of your virtual machine and select: **Devices** > **Shared Chipboard** > **Bidirectional**. - -To share files between the host OS and the virtual machine, select **Devices** > **Shared Folder** > **Shared Folder Settings**, right-click on **Machine Folders** and select **Add shared folder**. Enter the following information: - -* Folder path: `C:\Users\\` -* Folder name: `shared_folder` -* Mount point: `media` -* Select tick box **automount** -* Select tick box **Make Permanent** - -After this, a shared folder located in `/media/sf_shared_folder` is made available, which can be accessed from your host OS via the specified folder path. - -For convenience, a Terminal shortcut will be added to the desktop of the virtual machine. For this, open the Application menu by clicking on the icon in the upper left corner. Right-click on **Terminal Emulator** and select **Add to Desktop**. Open the terminal via the Desktop, it will show the following prompt: - - accellera@ebw:~:$ - -First, a few configurations should be done as superuser (`su`), such as adding user `accellera` to the sudoers group and install some base packages. Enter the following commands in the terminal window. After this, reboot the VM and login as accellera user again. - - $ su - - // enter accellera password - $ adduser accellera sudo - $ apt-get install git -y - $ reboot - -After the reboot, open the terminal window again. A workarea called `workarea` is created for the technical documentation. - - $ mkdir workarea - $ cd workarea - -Next, a clone of the repository is made, which contains the Accellera documentation flow and templates. - - $ git clone https://github.com/OSCI-WG/tc-documentation.git - $ cd tc-documentation - -NOTE---Each working group can have its own documentation repository. -{:.note} - -## A.5 Install documentation flow - -Install the Electric Book Works documentation flow by executing the following comment in the repository directory: - - $ cd tc-documentation # or working group specific documentation repository - $ bash setup.sh - -All packages for the documentation flow are installed. Also, Visual Studio Code is installed, which can be used as Markdown editor. - - -[virtualbox]: https://www.virtualbox.org/wiki/Downloads -[xubuntu]: https://cdimage.ubuntu.com/xubuntu/releases/jammy/release/ diff --git a/accellera-style-guide/images/screen-pdf/accellera_logo.svg b/accellera-style-guide/images/screen-pdf/accellera_logo.svg deleted file mode 100644 index 0f38a044..00000000 --- a/accellera-style-guide/images/screen-pdf/accellera_logo.svg +++ /dev/null @@ -1,2366 +0,0 @@ - - - - - - - - - - image/svg+xml - - - - - - - - - diff --git a/accellera-style-guide/images/screen-pdf/create_vm.png b/accellera-style-guide/images/screen-pdf/create_vm.png deleted file mode 100755 index 7fcd7563..00000000 Binary files a/accellera-style-guide/images/screen-pdf/create_vm.png and /dev/null differ diff --git a/accellera-style-guide/images/screen-pdf/vm_account.png b/accellera-style-guide/images/screen-pdf/vm_account.png deleted file mode 100755 index 3a568d99..00000000 Binary files a/accellera-style-guide/images/screen-pdf/vm_account.png and /dev/null differ diff --git a/accellera-style-guide/images/screen-pdf/vm_disk.png b/accellera-style-guide/images/screen-pdf/vm_disk.png deleted file mode 100755 index b74859ef..00000000 Binary files a/accellera-style-guide/images/screen-pdf/vm_disk.png and /dev/null differ diff --git a/accellera-style-guide/images/screen-pdf/vm_hardware.png b/accellera-style-guide/images/screen-pdf/vm_hardware.png deleted file mode 100755 index 0b9da7bf..00000000 Binary files a/accellera-style-guide/images/screen-pdf/vm_hardware.png and /dev/null differ diff --git a/bin/create b/bin/create new file mode 100755 index 00000000..c7150c58 --- /dev/null +++ b/bin/create @@ -0,0 +1,6 @@ +#!/bin/bash +docker run \ +-v $PWD/books:/home/adf/books \ +-v $PWD/metadata:/home/adf/_data/works \ +-v $PWD/output:/home/adf/_output \ +adf:v0.6 /bin/bash -c "npm run eb -- output --format screen-pdf --book '$@'" diff --git a/bin/create.bat b/bin/create.bat new file mode 100644 index 00000000..e0f29836 --- /dev/null +++ b/bin/create.bat @@ -0,0 +1,5 @@ +docker run ^ +-v %CD%\books:/home/adf/books ^ +-v %CD%\metadata:/home/adf/_data/works ^ +-v %CD%\output:/home/adf/_output ^ +adf:v0.6 /bin/bash -c "npm run eb -- output --format screen-pdf --book '%*'" diff --git a/bin/run b/bin/run new file mode 100755 index 00000000..add361e4 --- /dev/null +++ b/bin/run @@ -0,0 +1,6 @@ +#!/bin/bash +docker run \ +-v $PWD/books:/home/adf/books \ +-v $PWD/metadata:/home/adf/_data/works \ +-v $PWD/output:/home/adf/_output \ +-i -t adf:v0.6 /bin/bash diff --git a/bin/run.bat b/bin/run.bat new file mode 100644 index 00000000..cf225545 --- /dev/null +++ b/bin/run.bat @@ -0,0 +1,5 @@ +docker run ^ +-v %CD%\books:/home/adf/books ^ +-v %CD%\metadata:/home/adf/_data/works ^ +-v %CD%\output:/home/adf/_output ^ +-i -t adf:v0.6 /bin/bash diff --git a/accellera-style-guide/0-0-titlepage.md b/books/accellera-style-guide/0-0-titlepage.md similarity index 51% rename from accellera-style-guide/0-0-titlepage.md rename to books/accellera-style-guide/0-0-titlepage.md index 750e669d..3809d907 100644 --- a/accellera-style-guide/0-0-titlepage.md +++ b/books/accellera-style-guide/0-0-titlepage.md @@ -1,4 +1,5 @@ --- +# Copyright 2024 Accellera. All rights reserved. style: title-page --- diff --git a/accellera-style-guide/0-1-introduction.md b/books/accellera-style-guide/0-1-introduction.md similarity index 74% rename from accellera-style-guide/0-1-introduction.md rename to books/accellera-style-guide/0-1-introduction.md index f2fbacc4..c6007486 100644 --- a/accellera-style-guide/0-1-introduction.md +++ b/books/accellera-style-guide/0-1-introduction.md @@ -1,4 +1,5 @@ --- +# Copyright 2024 Accellera. All rights reserved. style: frontmatter --- @@ -6,13 +7,13 @@ style: frontmatter # Introduction -The Accellera Style Guide defines the recommended structure, formatting and style to develop and publish Accellera (Draft) Standards, User Guides and other standard-related documentation. This style guide serves as a reference for Accellera working groups in the technical editing process when drafting a standard-related document. +The Accellera Style Guide defines the recommended structure, formatting and style to develop and publish Accellera (Draft) Standards, User Guides and other standard-related documentation. This style guide serves as a reference for Accellera working groups in the technical editing process when drafting a standard-related document. The Accellera Style Guide is compatible with the IEEE SA Standards Style Manual, such that Accellera standards can be transferred to the IEEE Standardization Association, without the need to make fundamental changes to a document. Note that the Accellera Style Guide defines additional guidelines which are not explicitly documented in the IEEE SA Standards Style Manual, to ease the creation of Accellera and IEEE standard compatible documents. The Accellera Style Guide is owned and maintained by the Accellera Technical Committee. Working groups are encouraged to report findings and issues when using this style guide to the Accellera Technical Committee chair, such that improvements and learnings can be incorporated in this guide. -The Accellera Technical Committee also offers a documentation flow which is provided by [Electric Book Works](https://electricbookworks.com/). This documentation flow uses the Markdown format for authoring, and offers documentation generation to render the standard document in the required style. +Along with the Accellera Style Guide, the Accellera Documentation Flow (ADF) is made available to render standard documents in PDF format compliant with the IEEE SA Standards Style Manual. This documentation flow uses the Markdown format for authoring, and offers templates and automation to render the standard document in the required style. **Keywords**: {{ keywords }} diff --git a/accellera-style-guide/0-2-contents.md b/books/accellera-style-guide/0-2-contents.md similarity index 55% rename from accellera-style-guide/0-2-contents.md rename to books/accellera-style-guide/0-2-contents.md index b1efcba6..ca29a1b2 100644 --- a/accellera-style-guide/0-2-contents.md +++ b/books/accellera-style-guide/0-2-contents.md @@ -1,4 +1,5 @@ --- +# Copyright 2024 Accellera. All rights reserved. style: contents-page --- diff --git a/books/accellera-style-guide/0-3-list-figures.md b/books/accellera-style-guide/0-3-list-figures.md new file mode 100644 index 00000000..ffc78064 --- /dev/null +++ b/books/accellera-style-guide/0-3-list-figures.md @@ -0,0 +1,8 @@ +--- +# Copyright 2024 Accellera. All rights reserved. +style: contents-page +--- + +# List of figures + +{% include list-of-figures %} diff --git a/books/accellera-style-guide/0-4-list-tables.md b/books/accellera-style-guide/0-4-list-tables.md new file mode 100644 index 00000000..79a55aa5 --- /dev/null +++ b/books/accellera-style-guide/0-4-list-tables.md @@ -0,0 +1,8 @@ +--- +# Copyright 2024 Accellera. All rights reserved. +style: contents-page +--- + +# List of tables + +{% include list-of-tables %} diff --git a/books/accellera-style-guide/01.md b/books/accellera-style-guide/01.md new file mode 100644 index 00000000..b325120a --- /dev/null +++ b/books/accellera-style-guide/01.md @@ -0,0 +1,43 @@ +--- +# Copyright 2024 Accellera. All rights reserved. +style: chapter no-header +--- + +{% include metadata %} + +{{ title }} +{:.title} + +# 1. Overview + +## 1.1 Purpose + +This style guide defines the recommended structure, formatting and style to develop and deploy Accellera (Draft) Standards, User Guides and other standard-related documentation. + +This style guide is intended for Accellera working group members which are assigned as technical editor to author standard-related documentation. Technical editors are encouraged to contact the Accellera Technical Committee chair for additional guidance and support when developing a standard-related document. + +In the case of changes or deviations to the recommended formatting and style as defined in this guide, it is required to contact the Technical Committee chair for approval. Please note that deviations to the formatting and style may result in a delayed approval of the Accellera (draft) standard, or even difficulties to transfer an Accellera standard to the IEEE Standardization Association. + +This style guide is not addressing the policies and procedures for the development of Accellera standards. For that, please consult the [Accellera Policies & Procedures](https://www.accellera.org/images/about/policies/Policies_and_Procedures_2021.pdf) which can be found at the [Accellera](https://www.accellera.org/about/policies-and-procedures) website. + +## 1.2 Helpful resources + +The following documents are helpful resources for writing an Accellera standard-related document. + +[IEEE SA Standards Style Manual](https://mentor.ieee.org/myproject/Public/mytools/draft/styleman.pdf) + +[Electric Book documentation](https://electricbookworks.github.io/electric-book/docs/) + +[Kramdown Quick Reference](https://kramdown.gettalong.org/quickref.html) + +## 1.3 Accellera Documentation Flow + +It is strongly recommended to use the [Accellera Documentation Flow (ADF)](https://github.com/OSCI-WG/adf) to develop Accellera standard documents. When using this flow, the required Accellera or IEEE formatting and styles are automatically applied as part of the PDF rendering flow. + +Each Accellera working group will use its own GitHub repository to manage the source files of one or more documents. Working groups should contact the Technical Committee chair to request the creation of such documentation repository. + +The Accellera Documentation Flow is provided as Docker image. This flow offers the automation to render documents in PDF or HTML format. Technical editors who wish to render these documents should have a local installation of [Docker](https://docs.docker.com/get-started/). + +Note that installation of the Accellera Documentation Flow is not required when creating or authoring the document sources; in this case access to the GitHub repository and use of an text editor is sufficient. + +Please contact the Technical Committee chair in case of questions on the Accellera Documentation Flow, the required installation procedure or use of document styles and templates. diff --git a/books/accellera-style-guide/02.md b/books/accellera-style-guide/02.md new file mode 100644 index 00000000..d8b7309e --- /dev/null +++ b/books/accellera-style-guide/02.md @@ -0,0 +1,59 @@ +--- +# Copyright 2024 Accellera. All rights reserved. +style: chapter +--- + +# 2. Project setup + +This chapter explains the project setup and use of the GitHub repository for technical documentation. + +## 2.1 GitHub repository setup + +Each Accellera working group is encouraged to make use of a dedicated GitHub repository for technical documentation. Please contact the Technical Committee chair to request a new repository. A documentation repository will include the default templates to generate an Accellera or IEEE SA stylesheet compatible standards document. + +[Table 1](#table-1) below gives an overview of the initial structure of a documentation repository. + +{% include table + reference="Table 1" + caption="Repository structure" + class="fixed allow-break" + caption-position="top" + markdown=" +| Directory | Content | +|-----------------------------------------|---------------------------------------------------------| +| `books/` | Directory where all (examdocuments are stored | +| `books/accellera-standard-template/` | Directory containing the Accellera standard template | +| `books/ieee-sa-standard-template/` | Directory containing the IEEE SA standard template | +| `books/accellera-style-guide/` | Directory containing the Accellera Style Guide | +| `output/` | Output directory for generated PDF documents | +| `metadata/` | Document metadata (e.g. PDF properties) | +| `metadata/accellera-standard-template/` | Metadata of the Accellera standard template | +| `metadata/ieee-sa-standard-template/` | Metadata of the IEEE SA standard template | +| `metadata/accellera-style-guide/` | Metadata of the Accellera Style Guide | +| `README.md` | Information on the repository | +| `run` | Run script to launch the Docker container | +" +%} + +The repository contains templates to create Accellera or IEEE SA compliant standard documents. In addition, the sources of the Accellera Style Guide are supplied as a reference. +The metadata for these templates can be found in the directory `metadata`. + +When starting with the technical editing of a new standard, it is recommended use one of the standard templates as boilerplate code for the creation of the new standard document. This can be done by making a copy of the template and its metadata: + +``` +$ cd tc-documentation # or working group specific documentation repository + +# Copy and use of Accellera standard template +$ cp books/accellera-standard-template books/ +$ cp metadata/accellera-standard-template metadata/ + +# Copy and use of Accellera standard template +$ cp books/ieee-sa-standard-template books/ +$ cp metadata/ieee-sa-standard-template metadata/ +``` + +## 2.2 Accellera Documentation Flow setup + +[Annex A](a.md) explains the installation of a the Accellera Documentation Flow. + +Note that this flow is only required for the rendering and publication of the final standard document. For document editing and authoring, access to the GitHub project and availability of a simple text editor is sufficient. diff --git a/accellera-style-guide/03.md b/books/accellera-style-guide/03.md similarity index 95% rename from accellera-style-guide/03.md rename to books/accellera-style-guide/03.md index c13339ed..ee2b2226 100644 --- a/accellera-style-guide/03.md +++ b/books/accellera-style-guide/03.md @@ -1,4 +1,5 @@ --- +# Copyright 2024 Accellera. All rights reserved. style: chapter --- @@ -8,7 +9,7 @@ This chapter explains the document authoring and formatting. ## 3.1 Use of Markdown and kramdown syntax -The Accellera documentation flow uses [Markdown](https://en.wikipedia.org/wiki/Markdown) as primary text input format. More specifically, the [kramdown](https://kramdown.gettalong.org) flavor of Markdown is used, since it offers additional capabilities and extensions. +The Accellera Documentation Flow uses [Markdown](https://en.wikipedia.org/wiki/Markdown) as primary text input format. More specifically, the [kramdown](https://kramdown.gettalong.org) flavor of Markdown is used, since it offers additional capabilities and extensions. This section gives an overview of the commonly used structural elements. @@ -28,7 +29,7 @@ Like with paragraphs, separate the heading from everything else with an empty li This is a paragraph. ``` -By default, kramdown will automatically create an ID for each header, such that it can be referenced (see also [3.1.10.3](#31103-internal-links-cross-references)). +By default, kramdown will automatically create an ID for each header, such that it can be referenced (see also [3.1.10.3](#31103-internal-links--cross-references)). NOTE---The use of user-defined IDs is *not recommended*, as GitHub will not render these links correctly in the source files. {:.note} @@ -208,7 +209,7 @@ The table reference, caption and style can be added to the `{% raw %}{% include {% raw %} ``` {% include table - reference="Table 3" + reference="Table 2" caption="This is the table caption" class="fixed allow-break" caption-position="top" @@ -225,7 +226,7 @@ The table reference, caption and style can be added to the `{% raw %}{% include Renders into: {% include table - reference="Table 3" + reference="Table 2" caption="This is the table caption" class="fixed allow-break" caption-position="top" @@ -246,7 +247,7 @@ More complex table with merged cells or columns can be created using HTML syntax {% raw %} ``` {% include table - reference="Table 4" + reference="Table 3" caption="This is the a more complex table with merged rows and columns" class="fixed allow-break" caption-position="top" @@ -274,7 +275,7 @@ More complex table with merged cells or columns can be created using HTML syntax Renders into: {% include table - reference="Table 4" + reference="Table 3" caption="This is the a more complex table with merged cells and columns" class="fixed allow-break" caption-position="top" @@ -542,32 +543,31 @@ Within the document or document source tree, links can be added to files, clause *Example:* -``` -See [Chapter 1](01.html) for more information. -``` + +
        See [Chapter 1](01.md) for more information.
        Renders into -See [Chapter 1](01.html) for more information. +See [Chapter 1](01.md) for more information. To cross reference a subclause, use the header ID of that subclause. The default ID is a *slug* of the header, containing the section number and title. For example, for section 2.1 called “2.1 GitHub repository setup” the *slug* is `21-github-repository-setup`. Note that special characters like dots, backslash, etc. in the section title are skipped when creating the reference ID. In case the section is located in a different file, the file needs to be specified as well. *Example:* -``` -The GitHub repository setup is explained in [2.1](02.html#21-github-repository-setup). -``` + +
        The GitHub repository setup is explained in [2.1](02.md#21-github-repository-setup).
        + Renders into -The GitHub repository setup is explained in [2.1](02.html#21-github-repository-setup). +The GitHub repository setup is explained in [2.1](02.md#21-github-repository-setup). ### 3.1.11 HTML entities and Unicode characters -Special characters can be included using HTML entities or Unicode notation. [Table 5](#table-5) gives a brief overview of commonly used HTML entities and Unicode characters. A full overview can be found [here](https://www.rapidtables.com/code/text/unicode-characters.html). +Special characters can be included using HTML entities or Unicode notation. [Table 4](#table-4) gives a brief overview of commonly used HTML entities and Unicode characters. A full overview can be found [here](https://www.rapidtables.com/code/text/unicode-characters.html). {% include table - reference="Table 5" + reference="Table 4" caption="HTML entities and Unicode characters" class="fixed" caption-position="top" @@ -609,25 +609,26 @@ HTML attributes can be used to specify specific styles. ``` This is written in red. ``` + Renders into: This is written in red. ### 3.1.13 Inline comments -Inline comments can be added to the document source files, but these are excluded in the document rendering process. +Inline comments can be added to the document source files, but these are excluded in the document rendering process. A comment section may span multiple lines and starts with `{% raw %}{% comment %}{% endraw %}` and ends with `{% raw %}{% endcomment %}{% endraw %}`. *Example:* {% raw %} ``` -{% comment %} +{% comment %} These comments are visible for the technical editor of the document, but these are not rendered in the final output. {% endcomment %} ``` {% endraw %} -{% comment %} +{% comment %} These comments are visible for the technical editor of the document, but these are not rendered in the final output. {% endcomment %} @@ -662,10 +663,10 @@ For convenience, the following plain ASCII character sequences are available, wh ## 3.2 Formatting classes -[Table 6](#table-6) defines the classes which can be used in the Markdown source files to enforce specific formatting. +[Table 5](#table-5) defines the classes which can be used in the Markdown source files to enforce specific formatting. {% include table - reference="Table 6" + reference="Table 5" caption="Predefined formatting classes" class="fixed allow-break" caption-position="top" @@ -682,10 +683,10 @@ For convenience, the following plain ASCII character sequences are available, wh | Footnote | `.sidenote .bottom` | Block or inline | When adding `.bottom` to `.sidenote`, the footnote appears at the foot of the page in print output. It remains on the side on screens. | | Fractions | `.fractions` | Block or inline | If supported by the font, it converts characters like `1/2` into fraction characters. Add `{:.fractions}` to a span (e.g. italics, bold or link) or to a block element (e.g. list, paragraph) by adding it to the line immediately below it. | | Glossary | `.glossary` | Block | Add `{:.glossary}` below the last entry in a series of definition lists to format the entire list of definitions as a glossary. | -| Hide bookmark | `.no-bookmark` | Block | Hides the element from the PDF bookmarks. Apply `{:.no-bookmark}` below the element. | | Hide from print | `.non-printing` | Block or inline | Hides the element from print output. Useful for things like clickable buttons, which are only intended for screens, not paper. Apply `{:.non-printing}` below or next to the element. | | Hide markers of list items | `.list-no-markers` | Block | Hide list item markers (e.g., bullets, numbers or dashes) for num, while keeping the list formatting. Note: only works for the first level. Apply `{:.no-list-markers}` below the list. | -| Hide PDF bookmark | `.no-bookmark` | Block | Disable creation of PDF bookmark for section. Place `{:.no-bookmark}` directly under the header. (PrinceXML only.) | +| Hide PDF bookmark | `.no-bookmark` | Block | Hide section header in PDF bookmarks. Place `{:.no-bookmark}` directly under the header. (PrinceXML only.) | +| Hide from ToC | `.no-toc` | Block | Hide section header in table of contents (ToC). Place `{:.no-toc}` directly under the header. | | Keep together | `.keep-together` | Block or inline | Prevents an element from breaking across pages. (e.g., keep a short list on the same page.) Apply `{:.keep-together}` to the end of the entire element. You can also apply it to a span (e.g. a phrase, like 24/7) to prevent it breaking over a line. | | Keep with next | `.keep-with-next` | Block | Prevents a page break between this element and the next one. Apply `{:.keep-with-next}` below the first element, to make sure it stays with the following element. | | Line space above | `.space-above` | Block | Add line space above block. Spacing defined by `$line-height-default` property. Apply `{:.space-above}` below the block which requires additional spacing. | diff --git a/accellera-style-guide/04.md b/books/accellera-style-guide/04.md similarity index 99% rename from accellera-style-guide/04.md rename to books/accellera-style-guide/04.md index 16b14de4..1c7ecce1 100644 --- a/accellera-style-guide/04.md +++ b/books/accellera-style-guide/04.md @@ -1,4 +1,5 @@ --- +# Copyright 2024 Accellera. All rights reserved. style: chapter --- diff --git a/books/accellera-style-guide/a.md b/books/accellera-style-guide/a.md new file mode 100644 index 00000000..88e53998 --- /dev/null +++ b/books/accellera-style-guide/a.md @@ -0,0 +1,69 @@ +--- +# Copyright 2024 Accellera. All rights reserved. +style: annex +--- + +# Annex A **(informative)** Accellera Documentation Flow + +## A.1 Install Docker + +The Accellera Documentation Flow is available as Docker image. A local installation of [Docker](https://docs.docker.com/get-started/) is required run the Accellera Documentation Flow. Docker is available for Windows, Linux and Mac. Please follow the instructions on the Docker website to install Docker Desktop. + +## A.2 Install the Accellera Documentation Flow + +The Accellera Documentation Flow is made available as Docker image which can be downloaded from the Accellera Technical Committee [documentation workspace](https://workspace.accellera.org/wg/docwg/workgroup). Load the Docker image as follows: + +```bash +$ docker load -i adf_v0.5.tar.gz +``` + +Alternatively, the Docker image of the Accellera Documentation Flow can be built using one of the versions available in GitHub. The example below shows how to build version v0.5 of the flow: + +```bash +$ git clone --branch v0.5 https://github.com/OSCI-WG/adf.git +// enter your GitHub account and password/token to clone + +$ cd adf +$ docker build -t adf:v0.5 . +``` + +## A.3 Using the Accellera Documentation Flow + +Documents sources will be stored in separate documentation repositories. In the example below, the Accellera `tc-documentation` GitHub repository will be used: + +```bash +$ git clone https://github.com/OSCI-WG/tc-documentation.git +// enter your GitHub account and password/token to clone the repository + +$ cd tc-documentation +``` + +To generate a document, use the `create` command followed by the document to be generated. In the example below, we generate the PDF for the Accellera Style Guide: + +```bash +$ cd tc-documentation +$ ./create accellera-style-guide +``` + +It will generate the PDF document of the Accellera Style Guide in the `output` directory. In addition, the intermediate HTML files are stored in the directory `output/html`. + +In case section numbering is enabled, the updated Markdown source files are stored in `output/update`. The technical editor can compare them against the original source files in the `books` directory, and replace them if applicable. + +## A.4 Using the flow in interactive mode + +The Accellera Documentation Flow can also be executed in interative mode, by starting an interactive shell in the Docker container. For this, the `run` command can be used: + +```bash +$ cd tc-documentation +$ ./run +``` + +It will open a Bash shell within the Docker container. You can now render one of the documents available in the `books` directory using the Electic Book commands: + +```bash +adf@xyz $ npm run electric-book -- output --format screen-pdf --book accellera-style-guide +``` + +To close the interactive shell, type `exit` and it returns to your host shell. + +The list of Electic Book commands is available in [Annex B](b.md). diff --git a/accellera-style-guide/b.md b/books/accellera-style-guide/b.md similarity index 73% rename from accellera-style-guide/b.md rename to books/accellera-style-guide/b.md index e6847ca9..4fe1a748 100644 --- a/accellera-style-guide/b.md +++ b/books/accellera-style-guide/b.md @@ -1,4 +1,5 @@ --- +# Copyright 2024 Accellera. All rights reserved. style: annex --- @@ -8,9 +9,7 @@ style: annex ``` npm run electric-book -- [options] - -or - + or npm run eb -- [options] commands: @@ -44,7 +43,7 @@ options: -r, --app-release Make the app a signed release (default: false) -p, --app-emulate Launch app in default emulator (default: false) -x, --export-format File format to export to (default: MS Word) - -s, --section-numbering Depth of section (re)numbering in the book (default: 0) + -s, --section-numbering Depth of section (re)numbering in the book (default: -1) -j, --merged Whether to merge HTML files for PDF output (default: true) -z, --pdf-debug Enable PDF debug (PagedJS only) (default: false) -g, --pdf-engine Select PDF rendering engine (default: prince) @@ -53,32 +52,20 @@ options: ## B.2 Examples -Create a screen PDF for the Accellera standard template (`accellera-standard-template`) document: +Create a PDF for the Accellera Style Guide (`accellera-style-guide`): -``` -npm run electric-book -- output --format screen-pdf --book accellera-standard-template +```bash +$ npm run electric-book -- output --format screen-pdf --book accellera-style-guide ``` -Create a screen PDF for the Accellera Style Guide: +Create a PDF for the Accellera Style Guide, and enable renumbering of sections and cross-references down to the 5th level: -``` -npm run electric-book -- output --format screen-pdf --book accellera-style-guide +```bash +$ npm run electric-book -- output --format screen-pdf --book accellera-style-guide --section-numbering 5 ``` -Create a screen PDF for the Accellera Style Guide, and enable renumbering of sections and cross-references down to 5th level: - -``` -npm run electric-book -- output --format screen-pdf --book accellera-style-guide --section-numbering 5 -``` +Create a PDF for the IEEE SA Standards Style Manual (`ieee-sa-standards-style-manual`): -Create a screen PDF for the IEEE SA Standards Style Manual: - -``` -npm run electric-book -- output --format screen-pdf --book ieee-sa-standards-style-manual -``` - -Create a table of contents file for the Accellera standard template (`accellera-standard-template`) document: - -``` -npm run electric-book -- toc --book accellera-standard-template +```bash +$ npm run electric-book -- output --format screen-pdf --book ieee-sa-standards-style-manual ``` diff --git a/accellera-style-guide/equation-1.xml b/books/accellera-style-guide/equation-1.xml similarity index 100% rename from accellera-style-guide/equation-1.xml rename to books/accellera-style-guide/equation-1.xml diff --git a/accellera-style-guide/images/screen-pdf/accellera_logo.png b/books/accellera-style-guide/images/screen-pdf/accellera_logo.png similarity index 100% rename from accellera-style-guide/images/screen-pdf/accellera_logo.png rename to books/accellera-style-guide/images/screen-pdf/accellera_logo.png diff --git a/accellera-standard-template/images/screen-pdf/accellera_logo.svg b/books/accellera-style-guide/images/screen-pdf/accellera_logo.svg similarity index 100% rename from accellera-standard-template/images/screen-pdf/accellera_logo.svg rename to books/accellera-style-guide/images/screen-pdf/accellera_logo.svg diff --git a/accellera-style-guide/package.opf b/books/accellera-style-guide/package.opf similarity index 100% rename from accellera-style-guide/package.opf rename to books/accellera-style-guide/package.opf diff --git a/accellera-standard-template/styles/app.scss b/books/accellera-style-guide/styles/app.scss similarity index 100% rename from accellera-standard-template/styles/app.scss rename to books/accellera-style-guide/styles/app.scss diff --git a/accellera-standard-template/styles/epub.scss b/books/accellera-style-guide/styles/epub.scss similarity index 100% rename from accellera-standard-template/styles/epub.scss rename to books/accellera-style-guide/styles/epub.scss diff --git a/accellera-standard-template/styles/hyphenation.dic b/books/accellera-style-guide/styles/hyphenation.dic similarity index 100% rename from accellera-standard-template/styles/hyphenation.dic rename to books/accellera-style-guide/styles/hyphenation.dic diff --git a/accellera-standard-template/styles/print-pdf.scss b/books/accellera-style-guide/styles/print-pdf.scss similarity index 100% rename from accellera-standard-template/styles/print-pdf.scss rename to books/accellera-style-guide/styles/print-pdf.scss diff --git a/accellera-standard-template/styles/screen-pdf.scss b/books/accellera-style-guide/styles/screen-pdf.scss similarity index 100% rename from accellera-standard-template/styles/screen-pdf.scss rename to books/accellera-style-guide/styles/screen-pdf.scss diff --git a/accellera-standard-template/styles/web.scss b/books/accellera-style-guide/styles/web.scss similarity index 100% rename from accellera-standard-template/styles/web.scss rename to books/accellera-style-guide/styles/web.scss diff --git a/accellera-style-guide/toc.ncx b/books/accellera-style-guide/toc.ncx similarity index 100% rename from accellera-style-guide/toc.ncx rename to books/accellera-style-guide/toc.ncx diff --git a/ieee-sa-standards-style-manual/0-0-cover.md b/books/ieee-sa-standards-style-manual/0-0-cover.md similarity index 56% rename from ieee-sa-standards-style-manual/0-0-cover.md rename to books/ieee-sa-standards-style-manual/0-0-cover.md index 4d8acbff..06597bbb 100644 --- a/ieee-sa-standards-style-manual/0-0-cover.md +++ b/books/ieee-sa-standards-style-manual/0-0-cover.md @@ -1,4 +1,5 @@ --- +# Copyright 2021 IEEE. All rights reserved. title: "Cover" style: cover --- diff --git a/ieee-sa-standards-style-manual/0-1-introduction.md b/books/ieee-sa-standards-style-manual/0-1-introduction.md similarity index 96% rename from ieee-sa-standards-style-manual/0-1-introduction.md rename to books/ieee-sa-standards-style-manual/0-1-introduction.md index 2b28e608..d256a3ef 100644 --- a/ieee-sa-standards-style-manual/0-1-introduction.md +++ b/books/ieee-sa-standards-style-manual/0-1-introduction.md @@ -1,4 +1,5 @@ --- +# Copyright 2021 IEEE. All rights reserved. title: Introduction style: frontmatter --- diff --git a/ieee-sa-standards-style-manual/0-2-contents.md b/books/ieee-sa-standards-style-manual/0-2-contents.md similarity index 63% rename from ieee-sa-standards-style-manual/0-2-contents.md rename to books/ieee-sa-standards-style-manual/0-2-contents.md index e7b45b9c..c0a33e09 100644 --- a/ieee-sa-standards-style-manual/0-2-contents.md +++ b/books/ieee-sa-standards-style-manual/0-2-contents.md @@ -1,4 +1,5 @@ --- +# Copyright 2021 IEEE. All rights reserved. title: Contents style: contents-page --- diff --git a/ieee-sa-standards-style-manual/01.md b/books/ieee-sa-standards-style-manual/01.md similarity index 96% rename from ieee-sa-standards-style-manual/01.md rename to books/ieee-sa-standards-style-manual/01.md index f62b22c3..f89b4a5c 100644 --- a/ieee-sa-standards-style-manual/01.md +++ b/books/ieee-sa-standards-style-manual/01.md @@ -1,4 +1,5 @@ --- +# Copyright 2021 IEEE. All rights reserved. style: chapter no-header --- diff --git a/ieee-sa-standards-style-manual/02.md b/books/ieee-sa-standards-style-manual/02.md similarity index 99% rename from ieee-sa-standards-style-manual/02.md rename to books/ieee-sa-standards-style-manual/02.md index 5fea5a63..8034a7a4 100644 --- a/ieee-sa-standards-style-manual/02.md +++ b/books/ieee-sa-standards-style-manual/02.md @@ -1,4 +1,5 @@ --- +# Copyright 2021 IEEE. All rights reserved. style: chapter continued --- diff --git a/ieee-sa-standards-style-manual/03.md b/books/ieee-sa-standards-style-manual/03.md similarity index 96% rename from ieee-sa-standards-style-manual/03.md rename to books/ieee-sa-standards-style-manual/03.md index d0893911..a2eb0e82 100644 --- a/ieee-sa-standards-style-manual/03.md +++ b/books/ieee-sa-standards-style-manual/03.md @@ -1,4 +1,5 @@ --- +# Copyright 2021 IEEE. All rights reserved. style: chapter continued --- diff --git a/ieee-sa-standards-style-manual/04.md b/books/ieee-sa-standards-style-manual/04.md similarity index 93% rename from ieee-sa-standards-style-manual/04.md rename to books/ieee-sa-standards-style-manual/04.md index 60c7ec63..c66e6250 100644 --- a/ieee-sa-standards-style-manual/04.md +++ b/books/ieee-sa-standards-style-manual/04.md @@ -1,4 +1,5 @@ --- +# Copyright 2021 IEEE. All rights reserved. style: chapter continued --- diff --git a/ieee-sa-standards-style-manual/05.md b/books/ieee-sa-standards-style-manual/05.md similarity index 98% rename from ieee-sa-standards-style-manual/05.md rename to books/ieee-sa-standards-style-manual/05.md index 47a0e65f..48509335 100644 --- a/ieee-sa-standards-style-manual/05.md +++ b/books/ieee-sa-standards-style-manual/05.md @@ -1,4 +1,5 @@ --- +# Copyright 2021 IEEE. All rights reserved. style: chapter continued --- diff --git a/ieee-sa-standards-style-manual/06.md b/books/ieee-sa-standards-style-manual/06.md similarity index 93% rename from ieee-sa-standards-style-manual/06.md rename to books/ieee-sa-standards-style-manual/06.md index 1d980c43..e052986d 100644 --- a/ieee-sa-standards-style-manual/06.md +++ b/books/ieee-sa-standards-style-manual/06.md @@ -1,4 +1,5 @@ --- +# Copyright 2021 IEEE. All rights reserved. style: chapter continued --- diff --git a/ieee-sa-standards-style-manual/07.md b/books/ieee-sa-standards-style-manual/07.md similarity index 93% rename from ieee-sa-standards-style-manual/07.md rename to books/ieee-sa-standards-style-manual/07.md index bd9b7fd5..9d77e728 100644 --- a/ieee-sa-standards-style-manual/07.md +++ b/books/ieee-sa-standards-style-manual/07.md @@ -1,9 +1,10 @@ --- +# Copyright 2021 IEEE. All rights reserved. style: chapter continued --- # 7. Trademarks -Working groups shall research the proper usage guidelines for any trademarks appropriate for their drafts and ensure that no fees are required, limitations imposed, etc. This information is usually stated on the websites of the trademark owners. If used, any trademarked items shall be identified in the standard and marked as such (with either ® or ™), as appropriate, upon first reference. All trademarked items cited in standards shall be credited to the trademark owner in the frontmatter of the standard. Note that there are restrictions on trademark use. See [Clause 8](08.html). +Working groups shall research the proper usage guidelines for any trademarks appropriate for their drafts and ensure that no fees are required, limitations imposed, etc. This information is usually stated on the websites of the trademark owners. If used, any trademarked items shall be identified in the standard and marked as such (with either ® or ™), as appropriate, upon first reference. All trademarked items cited in standards shall be credited to the trademark owner in the frontmatter of the standard. Note that there are restrictions on trademark use. See [Clause 8](08.md). IEEE designations are trademarks of the IEEE and shall be identified as trademarks (® or ™, as appropriate) at first citation of each designation in the frontmatter and in the body of the draft. diff --git a/ieee-sa-standards-style-manual/08.md b/books/ieee-sa-standards-style-manual/08.md similarity index 97% rename from ieee-sa-standards-style-manual/08.md rename to books/ieee-sa-standards-style-manual/08.md index b8951009..8ee78870 100644 --- a/ieee-sa-standards-style-manual/08.md +++ b/books/ieee-sa-standards-style-manual/08.md @@ -1,4 +1,5 @@ --- +# Copyright 2021 IEEE. All rights reserved. style: chapter continued --- diff --git a/ieee-sa-standards-style-manual/09.md b/books/ieee-sa-standards-style-manual/09.md similarity index 97% rename from ieee-sa-standards-style-manual/09.md rename to books/ieee-sa-standards-style-manual/09.md index 802d7e18..096f36e2 100644 --- a/ieee-sa-standards-style-manual/09.md +++ b/books/ieee-sa-standards-style-manual/09.md @@ -1,4 +1,5 @@ --- +# Copyright 2021 IEEE. All rights reserved. style: chapter continued --- diff --git a/ieee-sa-standards-style-manual/10.md b/books/ieee-sa-standards-style-manual/10.md similarity index 99% rename from ieee-sa-standards-style-manual/10.md rename to books/ieee-sa-standards-style-manual/10.md index c578ad0d..fb92f88d 100644 --- a/ieee-sa-standards-style-manual/10.md +++ b/books/ieee-sa-standards-style-manual/10.md @@ -1,4 +1,5 @@ --- +# Copyright 2021 IEEE. All rights reserved. style: chapter continued --- diff --git a/ieee-sa-standards-style-manual/11.md b/books/ieee-sa-standards-style-manual/11.md similarity index 99% rename from ieee-sa-standards-style-manual/11.md rename to books/ieee-sa-standards-style-manual/11.md index 7f7734c8..2f61adbe 100644 --- a/ieee-sa-standards-style-manual/11.md +++ b/books/ieee-sa-standards-style-manual/11.md @@ -1,4 +1,5 @@ --- +# Copyright 2021 IEEE. All rights reserved. style: chapter continued --- @@ -73,7 +74,7 @@ The initial letter of each word in the title (except prepositions) should be cap > Draft Standard for the Application and Testing of\.\.\. -When an IEEE standard covers a limited range of quantities, such as voltage, current, power, and size, the numerical limits of the ranges covered shall be included in the title, scope, or purpose, wherever it first appears. The use of non-quantitative terms (such as high and low, large and small, wide and narrow) should be avoided. Abbreviations should be avoided in titles of standards, except in the case of units of measurement (kV, mm, etc.). However, if such use is warranted, the policy stated in [12.5](12.html#125-acronyms-and-abbreviations) shall be followed. +When an IEEE standard covers a limited range of quantities, such as voltage, current, power, and size, the numerical limits of the ranges covered shall be included in the title, scope, or purpose, wherever it first appears. The use of non-quantitative terms (such as high and low, large and small, wide and narrow) should be avoided. Abbreviations should be avoided in titles of standards, except in the case of units of measurement (kV, mm, etc.). However, if such use is warranted, the policy stated in [12.5](12.md#125-acronyms-and-abbreviations) shall be followed. ## 11.4 Abstract and keywords diff --git a/ieee-sa-standards-style-manual/12.md b/books/ieee-sa-standards-style-manual/12.md similarity index 96% rename from ieee-sa-standards-style-manual/12.md rename to books/ieee-sa-standards-style-manual/12.md index fa66bf58..19bdf27f 100644 --- a/ieee-sa-standards-style-manual/12.md +++ b/books/ieee-sa-standards-style-manual/12.md @@ -1,4 +1,5 @@ --- +# Copyright 2021 IEEE. All rights reserved. style: chapter continued --- @@ -33,7 +34,7 @@ Informative text (text provided for information only) includes the following: ### 12.2.1 General -The first clause of a standard, [Clause 1](01.html), shall always be an overview (except for amendments and corrigenda, which **do not** usually have an overview, scope, or purpose). If the standard contains normative references and definitions, they shall be [Clause 2](02.html) and [Clause 3](03.html), respectively. The clauses that follow [Clause 3](03.html) can be ordered in any way by the working group. If clause and subclause titles begin with numbers, they should be spelled out, unless unavoidable (e.g., 10BASE-T). +The first clause of a standard, [Clause 1](01.md), shall always be an overview (except for amendments and corrigenda, which **do not** usually have an overview, scope, or purpose). If the standard contains normative references and definitions, they shall be [Clause 2](02.md) and [Clause 3](03.md), respectively. The clauses that follow [Clause 3](03.md) can be ordered in any way by the working group. If clause and subclause titles begin with numbers, they should be spelled out, unless unavoidable (e.g., 10BASE-T). ### 12.2.2 The overview of the draft @@ -73,7 +74,7 @@ Include the definitions of “*shall*,” “*should*,” and “*may*” within ### 12.3.1 What is a normative reference? -In an IEEE standard normative references are those documents that contain material that must be understood and used to implement the standard.[^std] Thus, normative references are indispensable when applying the standard. The decision to include something as a normative reference in a standard should be made thoughtfully. Documents to which reference is made only for information or background, and documents that served merely as references in the preparation of the standard, are not normative references. Such documents may, however, be included in a bibliography. (See [Clause 19](19.html).) +In an IEEE standard normative references are those documents that contain material that must be understood and used to implement the standard.[^std] Thus, normative references are indispensable when applying the standard. The decision to include something as a normative reference in a standard should be made thoughtfully. Documents to which reference is made only for information or background, and documents that served merely as references in the preparation of the standard, are not normative references. Such documents may, however, be included in a bibliography. (See [Clause 19](19.md).) [^std]: If the standard is intended for adoption by another organization, the working group should consider requirements for normative references by that organization. Contact IEEE SA content publishing staff for information about specific requirements. @@ -145,7 +146,7 @@ For citing Internet sources, the following format should be used where \ -{% endraw %} +{:.no-bookmark.no-toc} For the purposes of this document, the following terms and definitions apply. The [IEEE Standards Dictionary Online](http://www.ieee.org/portal/innovate/products/standard/standards_dictionary.html) should be consulted for terms not defined in this clause.[^ref] @@ -243,7 +243,7 @@ Acronyms and abbreviations, followed by the full term only, should be listed in Within text, the acronym or abbreviation should follow the first use of the full term (the first time in the introduction, then the first time in the body of the document, and then the first time in any annexes in which the acronym appears). The abbreviation or acronym should be placed in parentheses when following the full term. -Exceptions to the convention listed above are approved SI units. SI unit symbols are not abbreviations and shall not be included in a list of abbreviations and acronyms. The treatment of letter symbols for units (e.g., mm for millimeter), letter symbols for quantities (e.g., *R* for resistance), and mathematical symbols (e.g., log for logarithm) is covered in IEEE Std 260.1 and IEEE Std 280 (see also [Clause 15](15.html)). +Exceptions to the convention listed above are approved SI units. SI unit symbols are not abbreviations and shall not be included in a list of abbreviations and acronyms. The treatment of letter symbols for units (e.g., mm for millimeter), letter symbols for quantities (e.g., *R* for resistance), and mathematical symbols (e.g., log for logarithm) is covered in IEEE Std 260.1 and IEEE Std 280 (see also [Clause 15](15.md)). ## 12.6 Annexes @@ -259,7 +259,7 @@ Normative annexes required for implementation of the standard and are placed aft Informative annexes are included in a standard for information only. Standards writers should carefully consider the nature of the material placed in informative annexes. Informative annex material is considered part of the balloted document and copyrighted to IEEE. As such, it shall be submitted to the IEEE SA Standards Board and is not subject to substantive or technical change after approval. -An example of an informative annex is a bibliography. See [Clause 19](19.html) for information about bibliographic style. +An example of an informative annex is a bibliography. See [Clause 19](19.md) for information about bibliographic style. ## 12.7 Indexes diff --git a/ieee-sa-standards-style-manual/13.md b/books/ieee-sa-standards-style-manual/13.md similarity index 81% rename from ieee-sa-standards-style-manual/13.md rename to books/ieee-sa-standards-style-manual/13.md index 19bd2b4d..e124813e 100644 --- a/ieee-sa-standards-style-manual/13.md +++ b/books/ieee-sa-standards-style-manual/13.md @@ -1,4 +1,5 @@ --- +# Copyright 2021 IEEE. All rights reserved. style: chapter continued --- @@ -6,7 +7,7 @@ style: chapter continued ## 13.1 Body clauses -The body of a standard is usually divided into several major clauses that are further divided into subclauses. The IEEE Standards system for numbering clauses uses Arabic numerals in sequence. A subclause should be numbered by adding a decimal point and number to the clause number (e.g., 5.1). Subclauses may be divided into further subclauses by adding a second decimal point and number (e.g., 5.1.1). Five numbers separated by decimal points is the maximum acceptable subdivision (e.g., 5.1.1.1.1). If necessary, the material should be reorganized to avoid subdivisions beyond this point. An exception to this numbering is allowed for amendments (see [20.2.1](20.html#2021-numbering-in-amendments-and-corrigenda) for information on numbering in amendments and corrigenda). +The body of a standard is usually divided into several major clauses that are further divided into subclauses. The IEEE Standards system for numbering clauses uses Arabic numerals in sequence. A subclause should be numbered by adding a decimal point and number to the clause number (e.g., 5.1). Subclauses may be divided into further subclauses by adding a second decimal point and number (e.g., 5.1.1). Five numbers separated by decimal points is the maximum acceptable subdivision (e.g., 5.1.1.1.1). If necessary, the material should be reorganized to avoid subdivisions beyond this point. An exception to this numbering is allowed for amendments (see [20.2.1](20.md#2021-numbering-in-amendments-and-corrigenda) for information on numbering in amendments and corrigenda). Clauses and subclauses should be divided into further subclauses only when there is more than one subclause. For example, Clause 1 should not have a 1.1 unless there is also a 1.2. @@ -26,7 +27,7 @@ Standards are not published with line numbers (although numbers should be includ ## 13.2 Numbering annexes -Consecutive capital letters and a title should be used to identify each annex. Text should be organized and numbered as described in [12.1](12.html#121-normative-and-informative-clauses), with the following exception: clause and subclause numbers should be prefaced with the identifying letter of the annex, followed by a period (see the example annex in Annex B). For standards containing only one annex, the letter A should appear in its title and should preface the clause and subclause numbers in the text. Figures and tables included in annexes should also carry the identifying letter of the annex in which they appear, followed by a period. For example, the first figure in Annex B should be identified as Figure B.1. +Consecutive capital letters and a title should be used to identify each annex. Text should be organized and numbered as described in [12.1](12.md#121-normative-and-informative-clauses), with the following exception: clause and subclause numbers should be prefaced with the identifying letter of the annex, followed by a period (see the example annex in Annex B). For standards containing only one annex, the letter A should appear in its title and should preface the clause and subclause numbers in the text. Figures and tables included in annexes should also carry the identifying letter of the annex in which they appear, followed by a period. For example, the first figure in Annex B should be identified as Figure B.1. ## 13.3 Lists diff --git a/ieee-sa-standards-style-manual/14.md b/books/ieee-sa-standards-style-manual/14.md similarity index 99% rename from ieee-sa-standards-style-manual/14.md rename to books/ieee-sa-standards-style-manual/14.md index 140298b9..128dc856 100644 --- a/ieee-sa-standards-style-manual/14.md +++ b/books/ieee-sa-standards-style-manual/14.md @@ -1,4 +1,5 @@ --- +# Copyright 2021 IEEE. All rights reserved. style: chapter continued --- diff --git a/ieee-sa-standards-style-manual/15.md b/books/ieee-sa-standards-style-manual/15.md similarity index 96% rename from ieee-sa-standards-style-manual/15.md rename to books/ieee-sa-standards-style-manual/15.md index df74a953..c13aa6cf 100644 --- a/ieee-sa-standards-style-manual/15.md +++ b/books/ieee-sa-standards-style-manual/15.md @@ -1,4 +1,5 @@ --- +# Copyright 2021 IEEE. All rights reserved. style: chapter continued --- @@ -6,7 +7,7 @@ style: chapter continued ## 15.1 Letter symbols and units -Letter symbols defined in applicable IEEE standards (see [Clause 2](02.html)) should be used in preparing mathematical expressions. (See [14.4](14.html#144-letter-symbols) for a discussion of letter symbols.) +Letter symbols defined in applicable IEEE standards (see [Clause 2](02.md)) should be used in preparing mathematical expressions. (See [14.4](14.md#144-letter-symbols) for a discussion of letter symbols.) All terms shall be defined, including both quantities and units, in a tabulation following the equation [see [Equation (1)](#formula-1)]. The list should be preceded by the word *where*, followed by the list of variables and corresponding definitions. See 4.5 in Annex B for an example. diff --git a/ieee-sa-standards-style-manual/16.md b/books/ieee-sa-standards-style-manual/16.md similarity index 97% rename from ieee-sa-standards-style-manual/16.md rename to books/ieee-sa-standards-style-manual/16.md index e76c00bf..5f38402f 100644 --- a/ieee-sa-standards-style-manual/16.md +++ b/books/ieee-sa-standards-style-manual/16.md @@ -1,4 +1,5 @@ --- +# Copyright 2021 IEEE. All rights reserved. style: chapter continued --- @@ -8,7 +9,7 @@ style: chapter continued Tables provide a clear and concise way of presenting large amounts of data in a small space. The example draft in Annex B shows examples of properly formatted tables. -Working groups shall obtain permission to use any table from another source, including from a manufacturer, prior to using it in a draft standard (see [Clause 5](05.html)). +Working groups shall obtain permission to use any table from another source, including from a manufacturer, prior to using it in a draft standard (see [Clause 5](05.md)). Formal tables should be given a number and a concise title, and they should be cited in the text with the word *Table* followed by the number. (See [16.2](#162-numbering-and-capitalization-in-tables) for information on the numbering of tables.) Tables should be boxed, ruled and organized to fit on a single page. with the term, “Table” and the table number, followed by an em dash and the table title, all on one line, centered above the top border of the table, as follows: “Table 1—Title”. If a table carries over to more than one page, complete column headings should be repeated at the top of successive pages. The table number and title, with the term, “continued,” in parentheses and in italics, should be repeated and centered above the top border of the table on the successive pages, as follows: “Table 1—Title *(continued)*.” @@ -29,7 +30,7 @@ Only the initial letter of the first word and proper nouns should be capitalized ### 16.3.1 Units of measure -Units of measure shall always be provided in the title (in parentheses); or preceded by a solidus in the column headings [e.g., for volts either *E*(V) or *E*/V would be acceptable]; or in a NOTE. The same units of measure shall be used throughout each column; ohms shall not be combined with megohms, millimeters with centimeters, or seconds with minutes. To save space, abbreviations and letter symbols should be used in column and line headings wherever possible. (See IEEE Std 260.1 and other standards referenced in [Clause 2](02.html) for the appropriate abbreviations and symbols for use in standards.) +Units of measure shall always be provided in the title (in parentheses); or preceded by a solidus in the column headings [e.g., for volts either *E*(V) or *E*/V would be acceptable]; or in a NOTE. The same units of measure shall be used throughout each column; ohms shall not be combined with megohms, millimeters with centimeters, or seconds with minutes. To save space, abbreviations and letter symbols should be used in column and line headings wherever possible. (See IEEE Std 260.1 and other standards referenced in [Clause 2](02.md) for the appropriate abbreviations and symbols for use in standards.) ### 16.3.2 Numerical values diff --git a/ieee-sa-standards-style-manual/17.md b/books/ieee-sa-standards-style-manual/17.md similarity index 99% rename from ieee-sa-standards-style-manual/17.md rename to books/ieee-sa-standards-style-manual/17.md index ce5f820e..95d2381f 100644 --- a/ieee-sa-standards-style-manual/17.md +++ b/books/ieee-sa-standards-style-manual/17.md @@ -1,4 +1,5 @@ --- +# Copyright 2021 IEEE. All rights reserved. style: chapter continued --- diff --git a/ieee-sa-standards-style-manual/18.md b/books/ieee-sa-standards-style-manual/18.md similarity index 90% rename from ieee-sa-standards-style-manual/18.md rename to books/ieee-sa-standards-style-manual/18.md index 3578260f..a54eef54 100644 --- a/ieee-sa-standards-style-manual/18.md +++ b/books/ieee-sa-standards-style-manual/18.md @@ -1,4 +1,5 @@ --- +# Copyright 2021 IEEE. All rights reserved. style: chapter continued --- @@ -12,7 +13,7 @@ The *IEEE SA Standards Board Operations Manual*, [6.4](https://standards.ieee.or ## 18.2 Footnotes -The *IEEE SA Standards Board Operations Manual*, [6.4](https://standards.ieee.org/about/policies/opman/sect6/#6.4) states that footnotes are informative. Footnotes in text may be included in a standard only for information, clarification, and/or aid applicable to the use of the standard. Mandatory requirements shall not be included in text footnotes Note that footnotes to tables and figures follow different rules (see [16.4](16.html#164-notes-and-footnotes-to-tables) and [17.3](17.html#173-notes-and-footnotes-to-figures)) and may contain normative information. +The *IEEE SA Standards Board Operations Manual*, [6.4](https://standards.ieee.org/about/policies/opman/sect6/#6.4) states that footnotes are informative. Footnotes in text may be included in a standard only for information, clarification, and/or aid applicable to the use of the standard. Mandatory requirements shall not be included in text footnotes Note that footnotes to tables and figures follow different rules (see [16.4](16164-notes-and-footnotes-to-tables) and [17.3](17.md#173-notes-and-footnotes-to-figures)) and may contain normative information. {:.keep-together} Footnotes in the frontmatter, body, and annexes should be numbered consecutively using Arabic numerals. When there are footnotes within tables and figures, they should be lettered. If a footnote is cited more than once, each additional citation should refer back to its first mention as follows: @@ -21,7 +22,7 @@ Footnotes in the frontmatter, body, and annexes should be numbered consecutively ## 18.3 Examples -Examples may be used as illustrations to foster understanding of the standard. Examples are not a normative part of the standard; therefore, requirements shall not be included in the text of the example. (See [10.2](10.html#102-that-and-which) and [19.2](19.html#192-citing-standards-in-a-bibliography) for illustrations of examples.) +Examples may be used as illustrations to foster understanding of the standard. Examples are not a normative part of the standard; therefore, requirements shall not be included in the text of the example. (See [10.2](10.md#102-that-and-which) and [19.2](19.md#192-citing-standards-in-a-bibliography) for illustrations of examples.) ## 18.4 Warnings and cautions diff --git a/ieee-sa-standards-style-manual/19.md b/books/ieee-sa-standards-style-manual/19.md similarity index 94% rename from ieee-sa-standards-style-manual/19.md rename to books/ieee-sa-standards-style-manual/19.md index 13c36329..c1805fd2 100644 --- a/ieee-sa-standards-style-manual/19.md +++ b/books/ieee-sa-standards-style-manual/19.md @@ -1,4 +1,5 @@ --- +# Copyright 2021 IEEE. All rights reserved. style: chapter continued --- @@ -99,5 +100,5 @@ For articles or sources that were consulted online, the URL should be listed alo ### 19.4.8 Open Source informative references -Informative references to Open Source software shall be listed in the bibliography. The requirements of item e) in [12.3.1](12.html#1231-what-is-a-normative-reference) do not apply to informative references; however, the Working Group should consider the source, stability, maintenance, and security of the Open Source that is informatively referenced. +Informative references to Open Source software shall be listed in the bibliography. The requirements of item e) in [12.3.1](12.md#1231-what-is-a-normative-reference) do not apply to informative references; however, the Working Group should consider the source, stability, maintenance, and security of the Open Source that is informatively referenced. diff --git a/ieee-sa-standards-style-manual/20.md b/books/ieee-sa-standards-style-manual/20.md similarity index 86% rename from ieee-sa-standards-style-manual/20.md rename to books/ieee-sa-standards-style-manual/20.md index 1d1bea5c..a6c8e954 100644 --- a/ieee-sa-standards-style-manual/20.md +++ b/books/ieee-sa-standards-style-manual/20.md @@ -1,4 +1,5 @@ --- +# Copyright 2021 IEEE. All rights reserved. style: chapter continued --- @@ -33,11 +34,11 @@ Editing instructions and text indicating the changes to the base document follow ### 20.2.1 Numbering in amendments and corrigenda -Amendments and corrigenda shall follow the clause numbering outlined in [Clause 13](13.html). However, if text is inserted between existing consecutive clauses or subclauses, an additional letter may be included in the heads (e.g., if clauses are inserted between Clause 4 and Clause 5, the new clauses would be labeled Clause 4A, Clause 4B, Clause 4C). This would also apply to subclauses (e.g., subclauses inserted between 4.1.3 and 4.1.4 would be labeled 4.1.3a, 4.1.3b, 4.1.3c). This numbering may be more appropriate for amendments with extensive changes that would affect numbering throughout the base standard (so it would be difficult to outline all the numbering changes that would occur), or for amendments to standards where exact references to clauses, figures, equations, and tables are required. +Amendments and corrigenda shall follow the clause numbering outlined in [Clause 13](13.md). However, if text is inserted between existing consecutive clauses or subclauses, an additional letter may be included in the heads (e.g., if clauses are inserted between Clause 4 and Clause 5, the new clauses would be labeled Clause 4A, Clause 4B, Clause 4C). This would also apply to subclauses (e.g., subclauses inserted between 4.1.3 and 4.1.4 would be labeled 4.1.3a, 4.1.3b, 4.1.3c). This numbering may be more appropriate for amendments with extensive changes that would affect numbering throughout the base standard (so it would be difficult to outline all the numbering changes that would occur), or for amendments to standards where exact references to clauses, figures, equations, and tables are required. -Additional amendments to a base standard may insert text between already amended clauses or subclauses. In these cases, numbering of clauses may become very complex. IEEE SA content publishing staff can assist with complex numbering formats. Working groups should consider a revision of the document in these instances. For tables and figures in amendments and corrigenda, clause or subclause numbering should follow the numbering outlined in [16.2](16.html#162-numbering-and-capitalization-in-tables) and [17.2](17.html#172-figure-numbering-and-titles). However, if an amendment or corrigenda inserts a table between consecutive tables, or a figure between consecutive figures, the addition of a letter may be used. +Additional amendments to a base standard may insert text between already amended clauses or subclauses. In these cases, numbering of clauses may become very complex. IEEE SA content publishing staff can assist with complex numbering formats. Working groups should consider a revision of the document in these instances. For tables and figures in amendments and corrigenda, clause or subclause numbering should follow the numbering outlined in [16.2](16.md#162-numbering-and-capitalization-in-tables) and [17.2](17.md#172-figure-numbering-and-titles). However, if an amendment or corrigenda inserts a table between consecutive tables, or a figure between consecutive figures, the addition of a letter may be used. -Exceptions may be made for numbering established in previously published amendments. Exceptions shall only be valid until a revision occurs, after which the numbering described in [Clause 13](13.html) will be implemented. [Table 3](#table-3) shows appropriate numbering formats that may be used for amendments and corrigenda. (See Annex C for examples of amendment numbering.) +Exceptions may be made for numbering established in previously published amendments. Exceptions shall only be valid until a revision occurs, after which the numbering described in [Clause 13](13.md) will be implemented. [Table 3](#table-3) shows appropriate numbering formats that may be used for amendments and corrigenda. (See Annex C for examples of amendment numbering.) ### 20.2.2 Editorial instructions in amendments and corrigenda diff --git a/ieee-sa-standards-style-manual/21.md b/books/ieee-sa-standards-style-manual/21.md similarity index 96% rename from ieee-sa-standards-style-manual/21.md rename to books/ieee-sa-standards-style-manual/21.md index 8eb71120..da166427 100644 --- a/ieee-sa-standards-style-manual/21.md +++ b/books/ieee-sa-standards-style-manual/21.md @@ -1,4 +1,5 @@ --- +# Copyright 2021 IEEE. All rights reserved. style: chapter continued --- diff --git a/ieee-sa-standards-style-manual/annex-a.md b/books/ieee-sa-standards-style-manual/annex-a.md similarity index 99% rename from ieee-sa-standards-style-manual/annex-a.md rename to books/ieee-sa-standards-style-manual/annex-a.md index 01569527..dbbd2dfe 100644 --- a/ieee-sa-standards-style-manual/annex-a.md +++ b/books/ieee-sa-standards-style-manual/annex-a.md @@ -1,4 +1,5 @@ --- +# Copyright 2021 IEEE. All rights reserved. style: annex --- diff --git a/ieee-sa-standards-style-manual/images/_source/cover.jpg b/books/ieee-sa-standards-style-manual/images/_source/cover.jpg similarity index 100% rename from ieee-sa-standards-style-manual/images/_source/cover.jpg rename to books/ieee-sa-standards-style-manual/images/_source/cover.jpg diff --git a/ieee-sa-standards-style-manual/images/_source/fig1.png b/books/ieee-sa-standards-style-manual/images/_source/fig1.png similarity index 100% rename from ieee-sa-standards-style-manual/images/_source/fig1.png rename to books/ieee-sa-standards-style-manual/images/_source/fig1.png diff --git a/ieee-sa-standards-style-manual/images/_source/fig2.png b/books/ieee-sa-standards-style-manual/images/_source/fig2.png similarity index 100% rename from ieee-sa-standards-style-manual/images/_source/fig2.png rename to books/ieee-sa-standards-style-manual/images/_source/fig2.png diff --git a/ieee-sa-standards-style-manual/images/app/cover.jpg b/books/ieee-sa-standards-style-manual/images/app/cover.jpg similarity index 100% rename from ieee-sa-standards-style-manual/images/app/cover.jpg rename to books/ieee-sa-standards-style-manual/images/app/cover.jpg diff --git a/ieee-sa-standards-style-manual/images/app/fig1.png b/books/ieee-sa-standards-style-manual/images/app/fig1.png similarity index 100% rename from ieee-sa-standards-style-manual/images/app/fig1.png rename to books/ieee-sa-standards-style-manual/images/app/fig1.png diff --git a/ieee-sa-standards-style-manual/images/app/fig2.png b/books/ieee-sa-standards-style-manual/images/app/fig2.png similarity index 100% rename from ieee-sa-standards-style-manual/images/app/fig2.png rename to books/ieee-sa-standards-style-manual/images/app/fig2.png diff --git a/ieee-sa-standards-style-manual/images/epub/cover.jpg b/books/ieee-sa-standards-style-manual/images/epub/cover.jpg similarity index 100% rename from ieee-sa-standards-style-manual/images/epub/cover.jpg rename to books/ieee-sa-standards-style-manual/images/epub/cover.jpg diff --git a/ieee-sa-standards-style-manual/images/epub/fig1.png b/books/ieee-sa-standards-style-manual/images/epub/fig1.png similarity index 100% rename from ieee-sa-standards-style-manual/images/epub/fig1.png rename to books/ieee-sa-standards-style-manual/images/epub/fig1.png diff --git a/ieee-sa-standards-style-manual/images/epub/fig2.png b/books/ieee-sa-standards-style-manual/images/epub/fig2.png similarity index 100% rename from ieee-sa-standards-style-manual/images/epub/fig2.png rename to books/ieee-sa-standards-style-manual/images/epub/fig2.png diff --git a/ieee-sa-standards-style-manual/images/print-pdf/cover.jpg b/books/ieee-sa-standards-style-manual/images/print-pdf/cover.jpg similarity index 100% rename from ieee-sa-standards-style-manual/images/print-pdf/cover.jpg rename to books/ieee-sa-standards-style-manual/images/print-pdf/cover.jpg diff --git a/ieee-sa-standards-style-manual/images/print-pdf/fig1.png b/books/ieee-sa-standards-style-manual/images/print-pdf/fig1.png similarity index 100% rename from ieee-sa-standards-style-manual/images/print-pdf/fig1.png rename to books/ieee-sa-standards-style-manual/images/print-pdf/fig1.png diff --git a/ieee-sa-standards-style-manual/images/print-pdf/fig2.png b/books/ieee-sa-standards-style-manual/images/print-pdf/fig2.png similarity index 100% rename from ieee-sa-standards-style-manual/images/print-pdf/fig2.png rename to books/ieee-sa-standards-style-manual/images/print-pdf/fig2.png diff --git a/accellera-style-guide/images/screen-pdf/cover.jpg b/books/ieee-sa-standards-style-manual/images/screen-pdf/cover.jpg similarity index 100% rename from accellera-style-guide/images/screen-pdf/cover.jpg rename to books/ieee-sa-standards-style-manual/images/screen-pdf/cover.jpg diff --git a/ieee-sa-standards-style-manual/images/screen-pdf/fig1.png b/books/ieee-sa-standards-style-manual/images/screen-pdf/fig1.png similarity index 100% rename from ieee-sa-standards-style-manual/images/screen-pdf/fig1.png rename to books/ieee-sa-standards-style-manual/images/screen-pdf/fig1.png diff --git a/ieee-sa-standards-style-manual/images/screen-pdf/fig2.png b/books/ieee-sa-standards-style-manual/images/screen-pdf/fig2.png similarity index 100% rename from ieee-sa-standards-style-manual/images/screen-pdf/fig2.png rename to books/ieee-sa-standards-style-manual/images/screen-pdf/fig2.png diff --git a/ieee-sa-standards-style-manual/images/web/cover-1024.jpg b/books/ieee-sa-standards-style-manual/images/web/cover-1024.jpg similarity index 100% rename from ieee-sa-standards-style-manual/images/web/cover-1024.jpg rename to books/ieee-sa-standards-style-manual/images/web/cover-1024.jpg diff --git a/ieee-sa-standards-style-manual/images/web/cover-2048.jpg b/books/ieee-sa-standards-style-manual/images/web/cover-2048.jpg similarity index 100% rename from ieee-sa-standards-style-manual/images/web/cover-2048.jpg rename to books/ieee-sa-standards-style-manual/images/web/cover-2048.jpg diff --git a/ieee-sa-standards-style-manual/images/web/cover-320.jpg b/books/ieee-sa-standards-style-manual/images/web/cover-320.jpg similarity index 100% rename from ieee-sa-standards-style-manual/images/web/cover-320.jpg rename to books/ieee-sa-standards-style-manual/images/web/cover-320.jpg diff --git a/ieee-sa-standards-style-manual/images/web/cover-640.jpg b/books/ieee-sa-standards-style-manual/images/web/cover-640.jpg similarity index 100% rename from ieee-sa-standards-style-manual/images/web/cover-640.jpg rename to books/ieee-sa-standards-style-manual/images/web/cover-640.jpg diff --git a/ieee-sa-standards-style-manual/images/web/cover-max.jpg b/books/ieee-sa-standards-style-manual/images/web/cover-max.jpg similarity index 100% rename from ieee-sa-standards-style-manual/images/web/cover-max.jpg rename to books/ieee-sa-standards-style-manual/images/web/cover-max.jpg diff --git a/ieee-sa-standards-style-manual/images/web/cover.jpg b/books/ieee-sa-standards-style-manual/images/web/cover.jpg similarity index 100% rename from ieee-sa-standards-style-manual/images/web/cover.jpg rename to books/ieee-sa-standards-style-manual/images/web/cover.jpg diff --git a/ieee-sa-standards-style-manual/images/web/fig1-1024.png b/books/ieee-sa-standards-style-manual/images/web/fig1-1024.png similarity index 100% rename from ieee-sa-standards-style-manual/images/web/fig1-1024.png rename to books/ieee-sa-standards-style-manual/images/web/fig1-1024.png diff --git a/ieee-sa-standards-style-manual/images/web/fig1-2048.png b/books/ieee-sa-standards-style-manual/images/web/fig1-2048.png similarity index 100% rename from ieee-sa-standards-style-manual/images/web/fig1-2048.png rename to books/ieee-sa-standards-style-manual/images/web/fig1-2048.png diff --git a/ieee-sa-standards-style-manual/images/web/fig1-320.png b/books/ieee-sa-standards-style-manual/images/web/fig1-320.png similarity index 100% rename from ieee-sa-standards-style-manual/images/web/fig1-320.png rename to books/ieee-sa-standards-style-manual/images/web/fig1-320.png diff --git a/ieee-sa-standards-style-manual/images/web/fig1-640.png b/books/ieee-sa-standards-style-manual/images/web/fig1-640.png similarity index 100% rename from ieee-sa-standards-style-manual/images/web/fig1-640.png rename to books/ieee-sa-standards-style-manual/images/web/fig1-640.png diff --git a/ieee-sa-standards-style-manual/images/web/fig1-max.png b/books/ieee-sa-standards-style-manual/images/web/fig1-max.png similarity index 100% rename from ieee-sa-standards-style-manual/images/web/fig1-max.png rename to books/ieee-sa-standards-style-manual/images/web/fig1-max.png diff --git a/ieee-sa-standards-style-manual/images/web/fig1.png b/books/ieee-sa-standards-style-manual/images/web/fig1.png similarity index 100% rename from ieee-sa-standards-style-manual/images/web/fig1.png rename to books/ieee-sa-standards-style-manual/images/web/fig1.png diff --git a/ieee-sa-standards-style-manual/images/web/fig2-1024.png b/books/ieee-sa-standards-style-manual/images/web/fig2-1024.png similarity index 100% rename from ieee-sa-standards-style-manual/images/web/fig2-1024.png rename to books/ieee-sa-standards-style-manual/images/web/fig2-1024.png diff --git a/ieee-sa-standards-style-manual/images/web/fig2-2048.png b/books/ieee-sa-standards-style-manual/images/web/fig2-2048.png similarity index 100% rename from ieee-sa-standards-style-manual/images/web/fig2-2048.png rename to books/ieee-sa-standards-style-manual/images/web/fig2-2048.png diff --git a/ieee-sa-standards-style-manual/images/web/fig2-320.png b/books/ieee-sa-standards-style-manual/images/web/fig2-320.png similarity index 100% rename from ieee-sa-standards-style-manual/images/web/fig2-320.png rename to books/ieee-sa-standards-style-manual/images/web/fig2-320.png diff --git a/ieee-sa-standards-style-manual/images/web/fig2-640.png b/books/ieee-sa-standards-style-manual/images/web/fig2-640.png similarity index 100% rename from ieee-sa-standards-style-manual/images/web/fig2-640.png rename to books/ieee-sa-standards-style-manual/images/web/fig2-640.png diff --git a/ieee-sa-standards-style-manual/images/web/fig2-max.png b/books/ieee-sa-standards-style-manual/images/web/fig2-max.png similarity index 100% rename from ieee-sa-standards-style-manual/images/web/fig2-max.png rename to books/ieee-sa-standards-style-manual/images/web/fig2-max.png diff --git a/ieee-sa-standards-style-manual/images/web/fig2.png b/books/ieee-sa-standards-style-manual/images/web/fig2.png similarity index 100% rename from ieee-sa-standards-style-manual/images/web/fig2.png rename to books/ieee-sa-standards-style-manual/images/web/fig2.png diff --git a/ieee-sa-standards-style-manual/package.opf b/books/ieee-sa-standards-style-manual/package.opf similarity index 100% rename from ieee-sa-standards-style-manual/package.opf rename to books/ieee-sa-standards-style-manual/package.opf diff --git a/accellera-style-guide/styles/app.scss b/books/ieee-sa-standards-style-manual/styles/app.scss similarity index 100% rename from accellera-style-guide/styles/app.scss rename to books/ieee-sa-standards-style-manual/styles/app.scss diff --git a/accellera-style-guide/styles/epub.scss b/books/ieee-sa-standards-style-manual/styles/epub.scss similarity index 100% rename from accellera-style-guide/styles/epub.scss rename to books/ieee-sa-standards-style-manual/styles/epub.scss diff --git a/accellera-style-guide/styles/hyphenation.dic b/books/ieee-sa-standards-style-manual/styles/hyphenation.dic similarity index 100% rename from accellera-style-guide/styles/hyphenation.dic rename to books/ieee-sa-standards-style-manual/styles/hyphenation.dic diff --git a/accellera-style-guide/styles/print-pdf.scss b/books/ieee-sa-standards-style-manual/styles/print-pdf.scss similarity index 100% rename from accellera-style-guide/styles/print-pdf.scss rename to books/ieee-sa-standards-style-manual/styles/print-pdf.scss diff --git a/accellera-style-guide/styles/screen-pdf.scss b/books/ieee-sa-standards-style-manual/styles/screen-pdf.scss similarity index 100% rename from accellera-style-guide/styles/screen-pdf.scss rename to books/ieee-sa-standards-style-manual/styles/screen-pdf.scss diff --git a/accellera-style-guide/styles/web.scss b/books/ieee-sa-standards-style-manual/styles/web.scss similarity index 100% rename from accellera-style-guide/styles/web.scss rename to books/ieee-sa-standards-style-manual/styles/web.scss diff --git a/ieee-sa-standards-style-manual/toc.ncx b/books/ieee-sa-standards-style-manual/toc.ncx similarity index 100% rename from ieee-sa-standards-style-manual/toc.ncx rename to books/ieee-sa-standards-style-manual/toc.ncx diff --git a/cci/0-0-titlepage.md b/cci/0-0-titlepage.md deleted file mode 100644 index 750e669d..00000000 --- a/cci/0-0-titlepage.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -style: title-page ---- - -{% include title-page %} diff --git a/cci/0-1-abstract.md b/cci/0-1-abstract.md deleted file mode 100644 index ace5bd06..00000000 --- a/cci/0-1-abstract.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -style: frontmatter ---- -{% include metadata %} - -**Abstract**: {{ description }} - -**Keywords**: {{ keywords }} diff --git a/cci/0-2-notice.md b/cci/0-2-notice.md deleted file mode 100644 index 091fd50f..00000000 --- a/cci/0-2-notice.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -style: frontmatter ---- - -# Notices - -**Accellera Systems Initiative (Accellera) Standards** documents are developed within Accellera and the Technical Committee of Accellera. Accellera develops its standards through a consensus development process, approved by its members and board of directors, which brings together volunteers representing varied viewpoints and interests to achieve the final product. Volunteers are members of Accellera and serve without compensation. While Accellera administers the process and establishes rules to promote fairness in the consensus development process, Accellera does not independently evaluate, test, or verify the accuracy of any of the information contained in its standards. - -Use of an Accellera Standard is wholly voluntary. Accellera disclaims liability for any personal injury, property or other damage, of any nature whatsoever, whether special, indirect, consequential, or compensatory, directly or indirectly resulting from the publication, use of, or reliance upon this, or any other Accellera Standard document. - -Accellera does not warrant or represent the accuracy or content of the material contained herein, and expressly disclaims any express or implied warranty, including any implied warranty of merchantability or suitability for a specific purpose, or that the use of the material contained herein is free from patent infringement. Accellera Standards documents are supplied **“AS IS.”** - -The existence of an Accellera Standard does not imply that there are no other ways to produce, test, measure, purchase, market, or provide other goods and services related to the scope of an Accellera Standard. Furthermore, the viewpoint expressed at the time a standard is approved and issued is subject to change due to developments in the state of the art and comments received from users of the standard. Every Accellera Standard is subjected to review periodically for revision and update. Users are cautioned to check to determine that they have the latest edition of any Accellera Standard. - -In publishing and making this document available, Accellera is not suggesting or rendering professional or other services for, or on behalf of, any person or entity. Nor is Accellera undertaking to perform any duty owed by any other person or entity to another. Any person utilizing this, and any other Accellera Standards document, should rely upon the advice of a competent professional in determining the exercise of reasonable care in any given circumstances. - -Interpretations: Occasionally questions may arise regarding the meaning of portions of standards as they relate to specific applications. When the need for interpretations is brought to the attention of Accellera, Accellera will initiate action to prepare appropriate responses. Since Accellera Standards represent a consensus of concerned interests, it is important to ensure that any interpretation has also received the concurrence of a balance of interests. For this reason, Accellera and the members of its Technical Committees are not able to provide an instant response to interpretation requests except in those cases where the matter has previously received formal consideration. - -Comments for revision of Accellera Standards are welcome from any interested party, regardless of membership affiliation with Accellera. Suggestions for changes in documents should be in the form of a proposed change of text, together with appropriate supporting comments. Comments on standards and requests for interpretations should be addressed to: - -> Accellera Systems Initiative.\\ -> 8698 Elk Grove Blvd Suite 1, #114\\ -> Elk Grove, CA 95624\\ -> USA - -Note: Attention is called to the possibility that implementation of this standard may require use of subject matter covered by patent rights. By publication of this standard, no position is taken with respect to the existence or validity of any patent rights in connection therewith. Accellera shall not be responsible for identifying patents for which a license may be required by an Accellera standard or for conducting inquiries into the legal validity or scope of those patents that are brought to its attention. -{:.note} - -Accellera is the sole entity that may authorize the use of Accellera-owned certification marks and/or trademarks to indicate compliance with the materials set forth herein. - -Authorization to photocopy portions of any individual standard for internal or personal use must be granted by Accellera, provided that permission is obtained from and any required fee is paid to Accellera. To arrange for authorization please contact Lynn Garibaldi, Accellera Systems Initiative, 8698 Elk Grove Blvd Suite 1, #114, Elk Grove, CA 95624, phone (916) 670-1056, e-mail . Permission to photocopy portions of any individual standard for educational classroom use can also be obtained from Accellera. - -Suggestions for improvements to the SystemC CCI Standard are welcome. They should be posted to the SystemC CCI Community Forum at: - -> - -The current Working Group web page is: - -> diff --git a/cci/0-3-introduction.md b/cci/0-3-introduction.md deleted file mode 100644 index 4806633a..00000000 --- a/cci/0-3-introduction.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -style: frontmatter ---- - -# Introduction - -| This introduction is informative and not part of the SystemC CCI standard - -This document defines the SystemC Configuration, Control and Inspection standard as a collection of C++ Application Programming -Interfaces (APIs) layered on top of the SystemC language standard; familiarity with the existing ISO C++ and IEEE 1666 SystemC standards -is presumed. - -SystemC Configuration represents phase one of the Configuration, Control and Inspection (CCI) standards for model- to-tool -interoperability. The primary use case is configuring variable properties of the structure and behavior of a model. This standard -facilitates consistent configurability of SystemC models from different providers and promotes a consistent user experience across -compliant tools. - -Stakeholders in SystemC Configuration include suppliers of electronic components and systems using SystemC to develop configurable models of their intellectual property, and Electronic Design Automation (EDA) companies that implement SystemC Configuration class libraries and -supporting tools. - -This standard is not intended to serve as a user’s guide or provide an introduction to SystemC Configuration. Readers requiring a SystemC -Configuration tutorial or information on its intended use should consult the Accellera Systems Initiative web site -(). - -# Acknowledgments - -The SystemC CCI Working Group would like to express gratitude to the following organizations for their extraordinary contributions to -development of the Configuration standard: -- **GreenSocs**, for contributing a complete Configuration solution which served as a concrete reference in defining the standard and also as a foundation for the reference implementation. -- **Ericsson**, for funding resources to fully develop the SystemC Configuration reference implementation. diff --git a/cci/0-4-participants.md b/cci/0-4-participants.md deleted file mode 100644 index aeeec6bb..00000000 --- a/cci/0-4-participants.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -style: frontmatter ---- - -# Participants - -At the time this Accellera standard was completed, the SystemC CCI Working Group had the following membership: - -| **Trevor Wieman**, Chair -| **Bart Vanthournout**, Vice Chair -{:.table-no-border.table-no-padding.table-text-center} - -| Daniel Aarno | Eric Frejd | Ahmed Nizamudheen -| Sergei Ananko | Enrico Galli | Atanas Parashkevov -| George Andre | Vishal Goel | P V S Phaneendra -| Guillaume Audeon | Thomas Goodfellow | Sonal Poddar -| John Aynsley | Karthick Gururaj | Udaya Ranga -| Martin Barnasconi | Philipp A Hartmann | Abhishek Saksena -| Laurent Bernard | Gino Hauwermeiren | Rauf Salimi Khaligh -| Bishnupriya Bhattacharya | Tor Jeremiassen | Christian Sauer -| David Black | Chandra Katuri | Martin Schnieringer -| Bill Bunton | Suresh Kumar | Ravi Singh -| Mark Burton | Erik Landry | Gary Snyder -| Sheshadri Chakravarthy | Glenn Leary | Henrik Svensson -| Somarka Chakravarti | Lei Liang | Ramachandran Swaminathan -| Ying-Tsai Chang | David Long | Yossi Veller -| Bryan Coish | Laurent Maillet-Contoz | CD Venkatesh -| Zaitrarrio Collier | Svetlin Manavski | Girish Verma -| Jerome Cornet | Scott McMahon | Eric Wallace -| Ola Dahl | Victoria Mitchell | Andy Walton -| Samik Das | Asif Mondal | Jesus Yuriar -| Guillaume Delbergue | Indraneel Mondal | Hakan Zeffer -| Ajit Dingankar | Vincent Motel | Rafael Zuralski -| Jakob Engblom | Rajiv Narayan -| Alan Fitch | Blake Nicholas -{:.table-no-border.table-no-padding.table-columns-fixed} - -The following members of the entity balloting committee voted on this standard. Balloters may have voted for approval, disapproval, or abstention. - -| ARM | Ericsson | Qualcomm -| Australian Semi | GreenSocs | ST -| Bosch | Intel | Synopsys -| Cadence | Mentor | TI -| CircuitSutra | NXP | Vayavya -| Doulos | OFFIS -{:.table-no-border.table-no-padding.table-columns-fixed} diff --git a/cci/0-5-contents.md b/cci/0-5-contents.md deleted file mode 100644 index e7b45b9c..00000000 --- a/cci/0-5-contents.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -title: Contents -style: contents-page ---- - -# Contents - -{% include toc %} diff --git a/cci/01.md b/cci/01.md deleted file mode 100644 index b316ec12..00000000 --- a/cci/01.md +++ /dev/null @@ -1,82 +0,0 @@ ---- -style: chapter document-title-page ---- - -{% include metadata %} - -{{ title }} -{:.title} - -# 1. Overview - -## 1.1 Scope - -This standard defines SystemC® Configuration as an ANSI standard C++ class library used to make SystemC models configurable.The standard does not specify a file format for specifying configuration *parameter values*. - -## 1.2 Purpose - -The general purpose of SystemC Configuration is to provide a standard for developing configurable SystemC models and supporting the -development of configuration tools. - -The specific purpose of this standard is to provide precise and complete definitions of (1) the SystemC Configuration class library -and (2) the interfaces necessary to implement *brokers* and to integrate existing *parameter* solutions. - -## 1.3 Word usage - -The word *shall* indicates mandatory requirements strictly to be followed in order to conform to the standard and from which no deviation is permitted (*shall* equals *is required to*).[^fn1], [^fn2] - -The word *should* indicates that among several possibilities one is recommended as particularly suitable, without mentioning or excluding others; or that a certain course of action is preferred but not necessarily required (*should* equals *is recommended that*). - -The word *may* is used to indicate a course of action permissible within the limits of the standard (*may* equals *is permitted to*). - -The word *can* is used for statements of possibility and capability, whether material, physical, or causal (*can* equals *is able to*). - -[^fn1]: The use of the word *must* is deprecated and cannot be used when stating mandatory requirements; *must* is used only to describe unavoidable situations. -[^fn2]: The use of *will* is deprecated and cannot be used when stating mandatory requirements; *will* is only used in statements of fact. - -### 1.3.1 Relationship with C++ (ISO/IEC 14882:2011) - -This standard is closely related to the C++ programming language and adheres to the terminology used in ISO/IEC 14882:2011. This standard -does not seek to restrict the usage of the C++ programming language; an *application* using the SystemC Configuration standard *may* use -any of the facilities provided by C++, which in turn *may* use any of the facilities provided by C. However, where the facilities provided -by this standard are used, they *shall* be used in accordance with the rules and constraints set out in this standard. - -This standard presumes that C++11 is the minimum revision supported and makes use of features of that revision such as move semantics. -Implementations *may* choose to support earlier revisions such as C++03 by hiding or approximating such features, however they are not -required to do so. - -This standard defines the public interface to the SystemC Configuration class library and the constraints on how those classes -may be used. The class library *may* be implemented in any manner whatsoever, provided only that the obligations imposed by this -standard are honored. - -A C++ class library may be extended using the mechanisms provided by the C++ language. Implementers and users are free to extend SystemC -Configuration in this way, provided that they do not violate this standard. - -NOTE---It is possible to create C++ programs that are legal according to the C++ programming language standard but violate this standard. An *implementation* is not obliged to detect every violation of this standard. -{:.note} - -### 1.3.2 Relationship with SystemC - -This standard is built on the IEEE Std 1666-2011 and extends it using the mechanisms provided by the C++ language, to provide an additional layer of configuration constructs. - -### 1.3.3 Guidance for readers - -Readers who are not familiar with SystemC Configuration should start with [Clause 4](04.html) which provides a brief -informal summary intended to aid in the understanding of the normative definitions. Such readers may also find it helpful to scan the -examples embedded in the normative definitions and to see the [Annex B](b.html) glossary. - -Readers should pay close attention to the terminology defined in [3.1](03.html#31-terminology) which is necessary for a precise interpretation of this standard. - -[Clause 5](05.html) defines the public interface to the SystemC Configuration class library. The following information is listed for each class: - 1. A brief class description. - 2. A C++ source code listing of the class definition. - 3. A statement of any constraints on the use of the class and its members. - 4. A statement of the semantics of the class and its members. - 5. For certain classes, a description of functions, typedefs, and macros associated with the class. - 6. Informative examples illustrating typical uses of the class. - -[Annex A](a.html) provides a practical introduction to the standard, heavily using example code to illustrate and demonstrate key concepts. - -[Annex C](c.html) provides recommended guidelines for effectively using this standard. - -[Annex D](d.html) describes how to enable the use of user-defined value types with configuration *parameters*. diff --git a/cci/02.md b/cci/02.md deleted file mode 100644 index b7292ed2..00000000 --- a/cci/02.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -style: chapter ---- - -# 2. Normative references - -The following documents are indispensable for the application of this document. Dated references indicate the minimum required version. - -This standard *shall* be used in conjunction with the following publications: - - ISO/IEC 14882:2011, Programming Languages – C++ - - IEEE Std 1666-2011: IEEE Standard SystemC Language Reference Manual - - ECMA-404:2017, The JSON Data Interchange Syntax diff --git a/cci/03.md b/cci/03.md deleted file mode 100644 index 35c2552e..00000000 --- a/cci/03.md +++ /dev/null @@ -1,167 +0,0 @@ ---- -style: chapter ---- - -# 3. Terminology and conventions used in this standard - -## 3.1 Terminology - -### 3.1.1 Shall, should, may, can - -See [1.3](01.html#13-word-usage) for the usage conventions regarding the words shall, should, may, and can. - -### 3.1.2 Application, implementation - -The word *application* is used to mean a C++ program, written by an end user, that uses the SystemC Configuration class library; that is, -uses classes, functions, or macros defined in this standard. - -The word *implementation* is used to mean any specific implementation of the SystemC Configuration class library as defined in this -standard, only the public interface of which need be exposed to the *application*. - -### 3.1.3 Call, called from, derived from - -The term *call* is taken to mean *call* directly or indirectly. *Call* indirectly means *call* an intermediate function that in turn calls -the function in question, where the chain of function calls may be extended indefinitely. - -Similarly, *called from* means called from directly or indirectly. - -Except where explicitly qualified, the term *derived from* is taken to mean derived directly or indirectly from. Derived indirectly from -means derived from one or more intermediate base classes. - -### 3.1.4 Specific technical terms - -The specific technical terms as defined in IEEE Std 1666-2011 generally apply for the SystemC Configuration standard. The term -*interface* is an exception, used herein to indicate a generic software interface (or application programming interface) which does -not require inheritance from **`sc_interface`**. - -In addition, the following technical terms are defined: - -A *parameter* is a class *derived from* the class **`cci::cci_param_if`**. - -A *broker* is a class *derived from* the class **`cci::cci_broker_if`**. - -## 3.2 Syntactical conventions - -### 3.2.1 Implementation-defined - -The italicized term *implementation-defined* is used where part of a C++ definition is omitted from this standard. In such cases, an -*implementation* shall provide an appropriate definition that honors the semantics defined in this standard. - -### 3.2.2 Ellipsis (...) - -An ellipsis, which consists of three consecutive dots (...), is used to indicate that irrelevant or repetitive parts of a C++ code listing -or example have been omitted for brevity. - -### 3.2.3 Class names - -Class names italicized and annotated with a superscript dagger (†) *should not* be used explicitly within an *application*. Moreover, an -*application* shall not create an object of such a class. It is strongly recommended that the given class name be used in an -implementation. However, an implementation *may* substitute an alternative class name in place of every occurrence of a particular -daggered class name. - -Only the class name is considered here. Whether any part of the definition of the class is *implementation-defined* is a separate -issue. - -The class names are the following: - - *`cci_value_cref`**†* - - *`cci_value_ref`**†* - - *`cci_value_list_cref`**†* - - *`cci_value_list_ref`**†* - - *`cci_value_map_cref`**†* - - *`*cci_value_map_ref`**†* - - *`cci_value_string_cref`**†* - - *`cci_value_string_ref`**†* - -Public typedefs are provided for these classes to avoid the need to refer to them directly. - -### 3.2.4 Configuration, Control and Inspection (CCI) naming patterns - -The CCI interoperability interfaces are denoted with the prefix **`cci_`** for classes, functions, global definitions and variables, and with the prefix **`CCI_`** for macros and enumeration values. - -An *application* shall not make use of these prefixes when defining classes, functions, global definitions, global variables, macros, and -enumerations. - -Class names ending in **`_if`**, such as **`cci_broker_if`** and **`cci_param_if`**, declare abstract C++ classes providing key interfaces which *must* be inherited and fully satisfied by every implementation of this standard. - -## 3.3 Typographical conventions - -The following typographical conventions are used in this standard: - - 1. The *italic* font is used for cross references to terms defined in - [3.1](#31-terminology), [3.2](#32-syntactical-conventions) and [Annex B](b.html).\\ - For example: “Each *parameter* is registered during construction with a single *broker*.” - 2. The **`bold constant-width`** (Courier) font is used for all reserved keywords of the SystemC Configuration standard as defined in - namespaces, macros, constants, enum literals, classes, member functions, data members and types.\\ - For example: “Actual *parameters* are created as instances of **`cci_param_typed`**, which in concert with its base class **`cci_param_untyped`** implements the **`cci_param_if`** interface.” - - 3. The `constant-width` font is used for all other code; primarily: - - SystemC Configuration class definitions including member functions, data members and data types - - SystemC Configuration examples when the exact usage is depicted. - For example: “**`cci_param`**` p("param", 17, "Demonstration parameter");`“ - -The conventions listed herein are for ease of reading only. Editorial inconsistencies in the use of typography are unintentional and have no normative meaning in this standard. - -## 3.4 Semantic conventions - -### 3.4.1 Class definitions and the inheritance hierarchy - -An *implementation* may differ from this standard in that an *implementation* may introduce additional base classes, class members, -and friends to the classes defined in this standard. An *implementation* may modify the inheritance hierarchy by moving class -members defined by this standard into base classes not defined by this standard. Such additions and modifications may be made as necessary in order to implement the semantics defined by this standard or in order to introduce additional functionality not defined by this standard. - -### 3.4.2 Function definitions and side-effects - -This standard explicitly defines the semantics of the C++ functions in the SystemC Configuration class library. Such functions *shall not* -have any side-effects that would contradict the behavior explicitly mandated by this standard. In general, the reader should assume the -common-sense rule that if it is explicitly stated that a function *shall* perform action A, that function *shall not* perform any action -other than A, either directly or by calling another function defined in this standard. However, a function *should* perform any tasks -necessary for resource management, performance optimization, or to support any ancillary features of an *implementation*. As an example -of resource management, it is assumed that a destructor will perform any tasks necessary to release the resources allocated by the -corresponding constructor. - -### 3.4.3 Exceptions - -Other than destructors and **`swap`** (see [5.5.2.3](05.html#5523-swap-functions)) or as explicitly noted in documentation, API functions should be presumed to have the potential to throw exceptions, either as the `SC_THROW` action from the `sc_report_handler::report` diagnostic or an explicit throw. *Callback* functions are also permitted to throw. *Implementations shall* ensure that class invariants are preserved in the case of exceptions from all sources. The utility function **`cci_handle_exception`** decodes CCI library exceptions using **`cci_param_failure`** enum values as described in [5.8](05.html#58-error-reporting). - -### 3.4.4 Functions whose return type is a reference or a pointer - -An object returned from a function by pointer or by reference is said to be valid during any period in which the object is not deleted and -the value or behavior of the object remains accessible to the *application*. If an *application* refers to the returned object after -it ceases to be valid, the behavior of the *implementation shall* be undefined. - -### 3.4.5 Functions that return \*this or a pass-by-reference argument - -In certain cases, the object returned is either an object `(*this)` returned by reference from its own member function (for example, the -assignment operators), or it is an object that was passed by reference as an argument to the function being *called*. In either case, the -function *call* itself places no additional obligations on the *implementation* concerning the lifetime and validity of the object -following return from the function *call*. - -### 3.4.6 Functions that return const char\* - -Certain functions have the return type **`const char*`** indicating they return a pointer to a null-terminated character string. Such -strings *shall* remain valid until returning from sc_main. - -### 3.4.7 Non-compliant applications and errors - -In the case where an *application* fails to meet an obligation imposed by this standard, the behavior of the implementation *shall* be -undefined in general. When this results in the violation of a diagnosable rule of the C++ standard, the C++ *implementation* will -issue a diagnostic message in conformance with the C++ standard. - -When this standard explicitly states that the failure of an *application* to meet a specific obligation is an *error* or a -*warning*, the *implementation shall* generate a diagnostic message by calling an appropriate function in **`cci_report_handler`**; for -common CCI error types the specific diagnostics such as **`set_param_failed`**, and for other errors or warnings -`sc_report_handler::report`. In the case of an *error*, the *implementation shall call* report with a severity of `SC_ERROR`. In -the case of a *warning*, the *implementation shall call* report with a severity of `SC_WARNING`. See [5.8](05.html#58-error-reporting) for details of **`cci_report_handler`**. - -An *implementation* or an *application* may choose to suppress run-time error checking and diagnostic messages because of -considerations of efficiency or practicality. For example, an *application* may *call* member function set_actions of class -sc_report_handler to take no action for certain categories of report. An *application* that fails to meet the obligations imposed by -this standard remains in error. - -There are cases where this standard states explicitly that a certain behavior or result is *undefined*. This standard places no obligations on the *implementation* in such a circumstance. In particular, such a circumstance may or may not result in an *error* or a *warning*. - -### 3.4.8 Notes and examples - -Notes appear at the end of certain subclauses, designated by the uppercase word NOTE. Notes often describe the consequences of rules -defined elsewhere in this standard. Certain subclauses include examples consisting of fragments of C++ source code. Such notes and -examples are informative to help the reader but are not an official part of this standard. diff --git a/cci/04.md b/cci/04.md deleted file mode 100644 index b3af8850..00000000 --- a/cci/04.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -style: chapter ---- - -# 4. CCI architecture overview - -The core of the SystemC Configuration standard is the pairing of *parameters* and *brokers*, where a *parameter* is a named instance of -a specific compile-time type and a *broker* aggregates *parameters* and provides access to them in the form of *handles*. *Brokers* and -*parameters* are both generally accessed via *handles* which, among other things, identify the source (“*originator*”) of new *parameter -value* assignments. Originator identification is commonly contextual and managed implicitly. - -Each *parameter* is registered during construction with a single *broker*. *Parameters* are typically constructed and owned by a -SystemC module, with other users subsequently obtaining a *handle* from the *broker*. The owner constructs a *parameter* with a *default -value*, however the *broker can* override this with a *preset value*, allowing tools to provide runtime configurations. - -Typically a *global broker* will exist, created early in the elaboration phase. Modules may supply their own *local brokers*, for -example to keep their *parameters* private. In such a case, a hierarchy of *brokers* mirrors the hierarchy of `sc_module`s. - -[Figure 1](#figure-1) shows a typical sequence of a *parameter* being constructed and used: - 1. A tool obtains a *broker handle* (**`cci_broker_handle`**, not explicitly shown) and specifies a *preset value* for the named - *parameter* (**`cci_param`**); this *should* be completed prior to construction of the owning module. - 2. The module owning the *parameter* instantiates it with a *default value*. - 3. The *parameter* registers with the *broker* (**`cci_broker_if`**) and acquires the *preset value*, supplanting the default. - 4. A user gets a *handle* for the *parameter* (**`cci_param_handle`**) and through it gets the current (i.e. *preset*) *value*. - -{% include figure - reference="Figure 1" - caption="Key interactions for parameter construction and access" - alt-text="" - class="fixed" - images="figure1.png" -%} - -It is useful to consider several perspectives when overviewing the more complete set of SystemC Configuration standard features: - - Tools\\ - Tools access *brokers* and *parameters* via *handles* and facilitate *parameter* interaction. A variant type is provided for exchanging*parameter values* in a highly portable manner referred to as “*untyped access*” as depicted in [Figure 1](#figure-1). Tools will also expose *parameter* attributes provided at construction (see *Parameter creation and direct access* below) as well as the origin of the current *value* and any metadata. Tools may utilize *broker callbacks* and *parameter callbacks* to report or respond to interesting events. - - *Parameter* creation and direct access\\ - Modules containing *parameters* will specify their compile-time type, description, and *default value*. They *may* provide additional metadata for the benefit of tools, users, and possibly other code. They *can* use *parameter callbacks* for reacting to *parameter* accesses. Ownership affords interacting with *parameters* directly, without *handles*. - - *Parameter* lookup and access via a *handle*\\ - SystemC code outside of the owning module will request a *broker handle* and in turn perform a name based lookup to obtain a *parameter handle*. With a few exceptions, such as inability to reset the parameter or override the *parameter*’s description and metadata, the *handle* provides an interface equivalent to the *parameter* itself. A testbench is one example of this perspective. - - (Sub-)System packaging and integration\\ - Local *brokers* are introduced at the time of packaging and/or integration to impose policies such as *parameter* hiding. - - Infrastructure\\ - Developers of modeling infrastructure will be concerned with enabling user-defined *parameter value* types and adapting legacy *parameter* implementations for conformance with the standard. diff --git a/cci/05.md b/cci/05.md deleted file mode 100644 index a9fd15df..00000000 --- a/cci/05.md +++ /dev/null @@ -1,2882 +0,0 @@ ---- -style: chapter ---- - -# 5. Configuration interfaces - -## 5.1 Namespaces - -The SystemC Configuration classes, functions and enumeration values *shall* be declared in two top-level C++ namespaces, **`cci`** and -**`cci_utils`**. An implementation *may* nest further namespaces within these two namespaces, but such nested namespaces shall not be used in *applications*. - -Namespace **`cci`** contains the classes, functions and enumeration values that comprise the interoperability interface for configuration. - -Namespace **`cci_utils`** contains utility classes that are not necessary for interoperability. Specifically, example broker -implementations are included to provide very basic broker services and to serve as a reference or starting point for more comprehensive -broker implementations. - -Namespace details are not shown in code listings herein in the interest of brevity. For the same reason, namespace qualification is -omitted from code samples where using namespace **`cci`** is assumed. - -## 5.2 Configuration header file - -To use SystemC Configuration class library features, an *application shall* include the top-level C++ header file at appropriate positions -in the source code as required by the scope and linkage rules of C++. - -``` -#include -``` - -The header file **`cci_configuration`** *shall* add the name **`cci`**, as well as the names defined in IEEE Std 1666-2011 for the header file named systemc, to the declarative region in which it is included. The header file **`cci_configuration`** *shall not* introduce into the declarative region, in which it is included, any other names from this standard or any names from the standard C or C++ libraries. - -*Example:* - -``` -#include -using cci::cci_param; -... -``` - -## 5.3 Enumerations - -### 5.3.1 cci_param_mutable_type - -Enumeration for the **`cci_param_typed`** template (see [5.6.2](#562-cci_param_typed)) specifying mutability of a *parameter*: - - **`CCI_MUTABLE_PARAM`** = 0 - The *parameter* is mutable and *can* be modified, unless it **`is_locked`** (see [5.4.2.6](#5426-protecting-parameters)). - - **`CCI_IMMUTABLE_PARAM`**\\ - The *parameter* is immutable, having either the *default value* with which it was constructed or a *preset value* configured through the *broker*. - NOTE: an immutable *parameter’s value* will change after being initialized (see [5.4.3.4](#5434-parameter-initialization)) only when the *preset value* has been updated and **`reset`** *called*. - - **`CCI_OTHER_MUTABILITY`** - Vendor specific mutability control. - -Mutability forms part of the concrete parameter type as an argument of the **`cci_param_typed`** template. - -### 5.3.2 cci_param_data_category - -Enumeration for the general category of a *parameter’s value* type; used when details of its specific type are not required. - - **`CCI_BOOL_PARAM`** – boolean valued *parameter* - - **`CCI_INTEGRAL_PARAM`** – integer valued *parameter* - - **`CCI_REAL_PARAM`** – real number valued *parameter* - - **`CCI_STRING_PARAM`** – string valued *parameter* - - **`CCI_LIST_PARAM`** – list valued *parameter* - - **`CCI_OTHER_PARAM`** – *parameter* with values of any other type - -### 5.3.3 cci_name_type - -Enumeration representing whether the name used in constructing a *parameter* is relative to the current module hierarchy: - - **`CCI_RELATIVE_NAME`** - Appended to the name of the enclosing `sc_module`, e.g. *parameter* “p” as a member of sub-module “sub” of top-level module “m” will have the full name “m.sub.p”. - - **`CCI_ABSOLUTE_NAME`** - The name isn’t modified. - -In either case the name is required to be unique and, if necessary, will be modified to make it so as described in [5.9](#59-name-support-functions) - -## 5.4 Core interfaces - -### 5.4.1 cci_originator - -*Originators* are used primarily to track the source, or origin, of *parameter values*. When a value originates from within the module -hierarchy, the originator *shall* be represented by the corresponding `sc_object`. When outside the module hierarchy, an originator *shall* be represented by a string name. - -``` -class cci_originator -{ - public: - inline cci_originator(); - cci_originator( const std::string& originator_name); - explicit cci_originator( const char* originator_name); - - // Copy constructors - cci_originator( const cci_originator& originator); - cci_originator( cci_originator&& originator); - - ~cci_originator(); - - const sc_core::sc_object* get_object() const; - - // Returns the name of the current originator - const char* name() const; - - // Operator overloads - cci_originator& operator=( const cci_originator& originator ); - cci_originator& operator=( cci_originator&& originator ); - bool operator==( const cci_originator& originator ) const; - bool operator<( const cci_originator& originator ) const; - - // Swap originator object and string name with the provided originator. - void swap( cci_originator& that ); - - // Returns the validity of the current originator - bool is_unknown() const; -}; -``` - -#### 5.4.1.1 Construction - -``` -cci_originator(); -``` - -The *originator* implicitly represents the current `sc_object` and will assume its name. This constructor form shall only be *called* from within the module hierarchy. - -``` -cci_originator( const std::string& originator_name ); -explicit cci_originator( const char* originator_name ); -``` - -Construct an *originator* with the explicit name; the `sc_object` will be a `nullptr`. This constructor form shall only be *called* from outside the module hierarchy. - -``` -cci_originator( const cci_originator& originator ); -cci_originator( cci_originator&& originator ); -``` - -Copy and move constructors initialize the object and name from the source. After a move the source **`cci_originator`** has a diagnostic “unknown” name and **`is_unknown`** returns `true`. - -#### 5.4.1.2 Copy and swap - -``` -cci_originator& operator=( const cci_originator& originator ); -cci_originator& operator=( cci_originator&& originator ); -``` - -Copy and move assignments, initializing the object and name from the source. After a move the source **`cci_originator`** has a diagnostic “unknown” name and **`is_unknown`** returns `true`. - -``` -void swap( cci_originator& that ); -``` - -Swaps the current **`cci_originator`** object and name with those of the provided **`cci_originator`**, with guaranteed exception safety. - -#### 5.4.1.3 Identity - -``` -const sc_core::sc_object* get_object() const; -``` - -Returns the *originator* object pointer. - -``` -const char* name() const; -``` - -Returns the name of the *originator*. When an *originator* `sc_object` exists, its name is returned; otherwise, the explicit name with which the *originator* was constructed. The returned pointer is non-owning and may be invalidated by the *originator*'s destruction. - -``` -bool is_unknown() const; -``` - -Returns `true` if no object or name is defined. Such a state is only likely where the object was the source of a move operation because -**`cci_originator`** reports an error if neither an *originator* object nor any name is given. - -*Example:* - -``` -cci_originator o1; -sc_assert( !o1.is_unknown() ); -cci_originator o2( std::move(o1) ); -sc_assert( o1.is_unknown() ); -``` - -#### 5.4.1.4 Comparisons - -``` -bool operator==( const cci_originator& originator ) const; -``` - -If either *originator* references an `sc_object`, then `true` is returned only if they both reference the same `sc_object`. Otherwise, `true` is returned if their names are equal. - -``` -bool operator<( const cci_originator& originator ) const; -``` - -Returns the result of comparing the names as strings. - -*Example:* - -``` -SC_CTOR( test_module ) { -cci_originator o1(); -cci_originator o2(); -sc_assert( o1 == o2 ); // both reference test_module -} -``` - -### 5.4.2 cci_param_if - -The basic *parameter* interface class, providing metadata and variant value access. Concrete descendant classes such as -**`cci_param_typed`** (see [5.6.2](#562-cci_param_typed)) provide *implementations*. In particular the **`cci_param_typed`** class -provides both the definition of the *underlying data type* and the instantiable object. - -``` -class cci_param_if : public cci_param_callback_if -{ - public: - // Get and set cci_value - cci_value get_cci_value() const; - virtual cci_value get_cci_value( const cci_originator& originator ) const = 0; - void set_cci_value( const cci_value& val ); - void set_cci_value( const cci_value& val, const cci_originator& originator ); - virtual void set_cci_value( - const cci_value& val, const void* pwd, const cci_originator& originator ) = 0; - virtual bool reset() = 0; - virtual cci_value get_default_cci_value() const = 0; - - // Value type - virtual cci_param_data_category get_data_category() const = 0; - virtual const std::type_info& get_type_info() const = 0; - - // Value origin - virtual bool is_default_value() const = 0; - virtual bool is_preset_value() const = 0; - virtual cci_originator get_originator() const = 0; - virtual cci_originator get_value_origin() const = 0; - - // Name and description - virtual const char* name() const = 0; - virtual std::string get_description() const = 0; - virtual void set_description( const std::string& desc ) = 0; - - // Metadata - virtual void add_metadata( const std::string& name, const cci_value& value, - const std::string& desc = "" ) = 0; - virtual cci_value_map get_metadata() const = 0; - - // Value protection - virtual cci_param_mutable_type get_mutable_type() const = 0; - virtual bool lock( const void* pwd = nullptr ) = 0; - virtual bool unlock( const void* pwd = nullptr ) = 0; - virtual bool is_locked() const = 0; - - // Equality - virtual bool equals( const cci_param_if& rhs ) const = 0; - - // Handle creation - virtual cci_param_untyped_handle - create_param_handle( const cci_originator& originator ) const = 0; - - protected: - virtual ~cci_param_if(); - void init( cci_broker_handle broker ); - void destroy( cci_broker_handle broker ); - - // Disabled - cci_param_if( cci_param_if&& ) = delete; - cci_param_if( const cci_param_if& ) = delete; - cci_param_if& operator=( cci_param_if&& ) = delete; - cci_param_if& operator=( const cci_param_if& ) = delete; - - private: - virtual void preset_cci_value( const cci_value& value, const cci_originator& originator ); - virtual void invalidate_all_param_handles(); - - // Get and set raw value - virtual void set_raw_value( const void* vp, const void* pwd, - const cci_originator& originator ) = 0; - virtual const void* get_raw_value( const cci_originator& originator ) const = 0; - virtual const void* get_raw_default_value() const = 0; - - virtual void add_param_handle( cci_param_untyped_handle* param_handle ) = 0; - virtual void remove_param_handle( cci_param_untyped_handle* param_handle ) = 0; -}; -``` - -#### 5.4.2.1 Value and data type - -The *parameter value* is handled via the variant type **`cci_value`**. Statically-typed access is provided by the descendant -**`cci_param_typed`** and matching **`cci_param_typed_handle`** classes. - -``` -cci_value get_cci_value() const; -cci_value get_cci_value( const cci_originator& originator ) const; -``` - -Returns a copy of the current *value*. The *originator* value identifies the context for pre- and post-read *callbacks*. If none -provided, the *parameter*’s own *originator* (typically the owning module) is used. - -``` -void set_cci_value( const cci_value& val ); -void set_cci_value( const cci_value& val, const cci_originator& originator ); -void set_cci_value( const cci_value& val, const void* pwd, const cci_originator& orig ); -``` - -Sets the *parameter* to a copy of the given *value*, applying the given password. A `nullptr` password is used if none is provided. If no -*originator* is provided, the *parameter*’s own *originator* is used. If the variant value cannot be unpacked to the *parameter*’s -*underlying data type* then a **`CCI_VALUE_FAILURE`** error is reported. - -``` -bool reset(); -``` - -Sets the *value* back to the *initial value* the *parameter* took, i.e. the *preset value* if one exists or the *default value* with -which it was constructed. Any pre-write *callbacks* are run before the *value* is reset, followed by any post-write *callbacks*, and finally the *value origin* is set to the original *originator* of the restored *value*. - -**`reset`** has no effect on a locked parameter and returns false; a locked parameter must be explicitly unlocked before a successful -**`reset`** can be performed. - -``` -cci_value get_default_cci_value() const; -``` - -Returns a copy of the *default value* the *parameter* was constructed with. - -``` -cci_param_data_category get_data_category() const; -``` - -Returns the *parameter*'s underlying data category. - -``` -const std::type_info& get_type_info() const; -``` - -Returns the C++ typeid of the *parameter*'s *underlying data type*. - -#### 5.4.2.2 Raw value access - -These private methods are accessible only by *parameter implementations*. They facilitate the exchange of *parameter values* -between arbitrary *parameter implementations* from levels in the *parameter* inheritance hierarchy where the specific *value* type is -not known. They provide no type safety. - -``` -void set_raw_value( const void* vp, const void* password, const cci_originator& originator ); -``` - -Overwrite the stored *value* with the given *value* `vp`, which *shall* point to a valid object of the *parameter*'s *underlying data type*. In detail: - - `vp` *shall not* be `nullptr` - - testing the write-lock state and the `password` validity if locked - - invoking pre-write *callbacks* with the given *originator*, aborting the write if *callbacks* reject it - - copying the value from vp - - invoking post-write *callbacks* with the given *originator* - - setting the *value origin* - -``` -const void* get_raw_value( const cci_originator& originator ) const; -``` - -Return a type-punned pointer to the *parameter*’s current *value* after first invoking the pre-read and then post-read -*callbacks*, both with the given *originator*. - -``` -const void* get_raw_default_value() const; -``` - -Return a type-punned pointer to the *parameter*’s *default value*. - -#### 5.4.2.3 Value origin - -Methods to determine the origin of the *parameter*’s current *value*: - -``` -bool is_default_value() const; -``` - -Returns `true` if the current *value* matches the *default value* with which the *parameter* was constructed, using the equality operator of the *underlying data type*. - -NOTE---this is a statement about the current *value* rather than its provenance; it does not mean that the *parameter value* is untouched -since its construction, simply that the current *value* matches the *default value*. -{:.note} - -``` -bool is_preset_value() const; -``` - -Returns `true` if the current *value* matches the *preset value* set via the *parameter*'s *broker* using -**`set_preset_cci_value`** see ([5.4.3.4](#5434-parameter-initialization)). Returns `false` if there is no *preset value*. - -The comparison is performed by the equality operator of the underlying data type against the unpacked *preset* **`cci_value`**. - -NOTE---this is a statement about the current *value* rather than its provenance; it does not mean that the *parameter value* is untouched -since its construction, simply that the current *value* matches the *preset value*. -{:.note} - -``` -cci_originator get_originator() const; -``` - -Returns a copy of the *originator* supplied when the *parameter* was constructed. - -``` -cci_originator get_value_origin() const; -``` - -Returns a copy of the *originator* of the most recent write to the *parameter value*: - 1. The *originator* supplied as a (possibly default) constructor argument when the *parameter* was constructed; semantically this - is the point where the *default value* was set. - 2. The *originator* supplied if the *preset value* was set by **`cci_broker_if::set_preset_cci_value`**. - 3. The *originator* supplied to explicit overloads of **`set_cci_value`** and **`set_raw_value`**. - 4. For all indirect writes via methods of **`cci_param_if`**, the constructor *originator* (described in case 1). - 5. For all writes via methods of **`cci_param_untyped_handle`** and **`cci_param_typed_handle`**, the *originator* given when - creating /getting the *handle*. - -#### 5.4.2.4 Name and description - -``` -const char* name() const; -std::string get_description() const; -void set_description( const std::string& desc ); -``` - -**`name`** returns the guaranteed-unique form of the name given when constructing the (*typed*) *parameter* (see [5.9](#59-name-support-functions)). - -A *parameter may* carry a textual description, given as a `std::string`. An application is encouraged to use this to ensure that *parameters* are adequately documented, e.g. when enumerated in log files. The description is initialized during construction of the concrete **`cci_param_typed`** object but *may* be subsequently updated via the *parameter* object (not a *handle*) using **`set_description`** and retrieved with **`get_description`**. - -#### 5.4.2.5 Metadata - -``` -void add_metadata( const std::string& name, const cci_value& value, const std::string& desc = "" ); -cci_value_map get_metadata() const; -``` - -A *parameter may* carry arbitrary metadata, presented as a **`cci_value_map`** of **`cci_value_list`** pairs (**`cci_value`** -value, `std::string` description). Metadata items are added piecewise using **`add_metadata`** and *shall* not be modified or removed since there is no direct access to the underlying map. The metadata is accessed through the return value of **`get_metadata`**, which is a deep copy of the metadata (in contrast to the reference returned by **`cci_value::get_map`**). This may be a performance consideration -if using metadata extensively. - -*Example:* - -``` -p.add_metadata( "alpha", cci_value( 2.0 ) ); // description defaulted -p.add_metadata( "beta", cci_value( "faint" ), "Beta description" ); -cci_value_map meta = p.get_metadata(); -cci_value::const_list_reference val = meta["beta"].get_list(); -sc_assert( val[0].get_string() == "faint" ); -sc_assert( val[1].get_string() == "Beta description" ); -``` - -#### 5.4.2.6 Protecting parameters - -Although *parameters* are commonly both visible and modifiable this may be undesirable: - - Discoverable *parameters* may become an inadvertent API. Adding the *parameters* to a *local broker can* prevent discovery. - - Model structure is generally fixed after the elaboration phase, so being able to modify structural *parameters* during the simulation - can mislead. Restricting the *parameter*’s mutability to **`CCI_IMMUTABLE_PARAM`** will reject such misuse with a **`CCI_SET_PARAM_FAILURE`** (see [5.8](#58-error-reporting)) error. - - *Parameters may* be modifiable during simulation but locked as read-only for an application, for example used to publish status. - The publisher *may* **`unlock`** the *parameter* prior to updating it, then **`lock`** it again, or more concisely use a setter that - accepts a password (but note the special-case behavior of `nullptr` passwords below). Attempts to change a locked *parameter’s value* - without a password are rejected with a **`CCI_SET_PARAM_FAILURE`** error. - -NOTE---*parameter* locking is orthogonal to *parameter* mutability: a **`CCI_IMMUTABLE_PARAM`** *may* be locked and unlocked again but will remain always read-only. -{:.note} - -``` -cci_param_mutable_type get_mutable_type() const; -``` - -Returns the *parameter*'s mutability type as described in [5.3.1](#531-cci_param_mutable_type) - -``` -bool lock( const void* password = nullptr ); -``` - -**`lock`** makes the *parameter*’s *value* password protected: - - if the *parameter* is unlocked then it becomes locked with a “password” address (ideally some pointer specific to the locking - entity, such as its own `this`): - - the given password, if it is not `nullptr` - - otherwise, with an *implementation-defined* private password unique to the *parameter*; a *parameter* locked in this way *shall* be explicitly unlocked for its *value* to be set; setters that delegate to **`set_cci_value`** and **`set_raw_value`** with a `nullptr` password will not override the lock (as would happen with an explicit non `nullptr` password) - - if the *parameter* is locked then: - - if it already has the given password then it remains locked with it - - if it has the default nullptr password then this is upgraded to the given password - - otherwise it remains locked by the previous password - -**`lock`** returns `true` if the *parameter* is now locked with the given password; returning `false` means the *parameter* is also locked but previously by some other password. - -``` -bool unlock( const void* password = nullptr ); -``` - -To unlock a locked *parameter*, *call* **`unlock`** with the same password used for the latest successful *call* to **`lock`**. If locked -without a password, a parameter *may* also be unlocked (by anyone) without a password. It returns `true` if the *parameter* became unlocked -from this *call*, `false` otherwise (i.e. either the *parameter* remains locked or it was already unlocked). - -NOTE---locking does not nest; a *parameter* locked twice with the same password will be unlocked by a single **`unlock`** with that password. -{:.note} - -``` -bool is_locked() const; -``` - -Returns `true` if the *parameter* is currently locked. - -#### 5.4.2.7 Equality test - -``` -bool equals( const cci_param_if& rhs ) const; -``` - -Returns `true` if both the type and *value* of the *parameter* argument match this *parameter* as determined by **`get_type_info`** and **`get_raw_value`**. The *value* comparison is delegated to the *parameter*’s *underlying data type*. - -*Example:* - -``` -cci_param iS( "iS", 3 ); -cci_param iL( "iL", 3 ); -sc_assert( !iS.equals( iL ) ); // short and long are distinct types -sc_assert( iS.get_cci_value() == iL.get_cci_value() ); // but all integer types do fit "3" -``` - -#### 5.4.2.8 Callbacks - -*Callback* functions *may* be registered for access to the *parameter value*. The complete *callback* interface is extensive since it is the product of functions supporting different phases of invocation, different *parameter* data types, both global and member functions, -and is distributed across both *typed* and *untyped parameter* classes and both object and - -*handle* interfaces. Therefore the treatment here is not a monolithic exploration of the functions but decomposes it structurally. Although *parameter* types are a property of the *derived typed* classes, they are discussed here so as to have a single coherent description of *callbacks*. - -*Callbacks shall* be registered against one of the stages of *value* access: - 1. **`register_pre_read_callback`**: - - *callback* is invoked before the *value* is read - - signature: `void callback(const cci_param_read_event& ev)` - 2. **`register_post_read_callback`**: - - *callback* is invoked after the *value* is read (i.e. just - before the *value* read is returned to the caller) - - signature: `void callback(const cci_param_read_event& ev)` - 3. **`register_pre_write_callback`**: - - *callback* is invoked before the new *value* is written - - *callback* is explicitly a validator for the new *value*; by - returning `false` it signals that the write *should not* - proceed, in which case a **`CCI_SET_PARAM_FAILURE`** error - report is immediately issued - - signature: `bool callback(const cci_param_write_event& ev)` - 4. **`register_post_write_callback`**: - - *callback* is invoked after the new *value* is written - - signature: `void callback(const cci_param_write_event& ev)` - -Multiple *callbacks* may be registered for each stage in which case they will be invoked in the order of their registration. If a -*callback* throws an exception (including as part of error reporting) then this immediately propagates through the cci framework code -without further *callbacks* being invoked and leaving all existing state modifications intact. For example a throw from a post-write -*callback* will leave the *parameter* with the new *value*, which may surprise a user expecting assignment to have the commonly-supported -copy-and-swap semantics. If *callbacks* are used to update complex state then consideration *should* be given to at least providing a -basic exception guarantee (that system invariants are not violated). - -The event object passed to the *callback* function carries the current *parameter value*, and also the new *value* for pre/post-write -*callbacks*. Event objects passed to *callbacks* registered through the *typed* parameter interface -**`cci_param_typed`**`` / **`cci_param_typed_handle`**`` convey the *values* as references to the actual type T. Event objects -passed to *callbacks* registered through the *untyped parameter* interface **`cci_untyped_param`** / **`cci_param_untyped_handle`** -convey the *values* as references to **`cci_value`**. - -For each access stage a pair of overloads exists for registering *callbacks*: one which creates a functor from the given -global/class-static method and another which creates a functor for the given member function: - -*Example:* - -``` -cci_callback_untyped_handle h1 = - param.register_pre_read_callback( &global_callback ); -cci_callback_untyped_handle h2 = - param.register_pre_read_callback( &myclass::member_callback, &myclass_object ); -``` - -Note that registration functions of this form are not present in the basic **`cci_param_if`**, but are introduced in -**`cci_param_untyped`** and **`cci_param_untyped_handle`** for *callbacks* with *untyped* event objects (see [5.6.2.6](#5626-callbacks)), and **`cci_param_typed`** and **`cci_param_typed_handle`** for *callbacks* with *typed* event objects (see [5.6.4.4](#5644-callbacks)). - -Although the *handle* object returned from *callback* registration encapsulates the function to be *called* and its arguments, from an -application perspective it's an opaque token to be used if the *callback* is to be explicitly unregistered: - -*Example:* - -``` -bool success = param.unregister_pre_read_callback( h1 ); -``` - -returning `true` if that *callback handle* was successfully removed from the *callbacks* for that phase. A specific *callback shall* be -unregistered by providing the *callback handle* returned when it was registered and unregistering against the correct access stage. -Specifically, the *handle* returned from **`register_pre_write_callback`** *shall* be passed to **`unregister_pre_write_callback`**. - -Unregistration is only necessary if the *callback* is to be suppressed during the lifetime of the *parameter*, since it is not an error to destroy a *parameter* that has *callbacks* remaining registered. `true` is returned if the unregistration was successful. The *callback handle* is only useful for later unregistration; if the *callback* is to remain for the lifetime of the *parameter* then the *handle* need not be stored. - -Lambda functions may also be conveniently used, either simply in place of an explicit function: - -*Example:* - -``` -// Running count of times that parameter is set to zero -param.register_post_write_callback( [this](auto ev){ this->num_zeroes += ev.new_value == 0; } ); -``` - -or to adapt a generic member function with instance-specific *parameters*: - -*Example:* - -``` -void audit::updated( const cci::cci_param_write_event& ev, string category ); -// Updates to wheels register as mileage, those to axles register as maintenance, C++11 -wheel1.register_post_write( [this](auto ev){ this->updated(ev, "mileage");} ); -wheel2.register_post_write( [this](auto ev){ this->updated(ev, "mileage");} ); -shaft.register_post_write( [this](auto ev){ this->updated(ev, "maintenance");} ); -``` - -Achieving similar results in a C++03 environment (given a C++03-supporting implementation of CCI): - -*Example:* - -``` -// Running count of times that parameter is set to zero -void count_zero_writes( const cci_param_write_event& ev ) { - num_zeroes += ev.new_value == 0; -} -param.register_post_write_callback( audit::count_zero_writes, this ); -``` - -and to adapt a function, `sc_bind` *can* be used: - -*Example:* - -``` -wheel1.register_post_write( sc_bind(&audit::updated, this, sc_unnamed::_1, "mileage") ); -wheel2.register_post_write( sc_bind(&audit::updated, this, sc_unnamed::_1, "mileage") ); -shaft.register_post_write( sc_bind(&audit::updated, this, sc_unnamed::_1, "maintenance") ); -``` - -##### Basic registration interface - -The interface provided through **`cci_param_if`** is intended for use by *derived parameters* and *parameter handles*. An application will -find it more convenient to use the registration overloads exposed by those classes. Only the pre-read phase is detailed here; the behavior of the other three phases is essentially the same: - -The *callback handle* is paired with the given *originator* and appended to the list of pre-read *callbacks*, and a copy of the -*callback handle* is returned. The *originator* is presented to the *callback* through **`cci_param_[read|write]_event::originator`**. - -##### Unregistering all callbacks: - -In addition to unregistering a specific *callback handle*, all *callbacks* for all four phases registered by a specific - -*originator may* be removed: - -``` -bool unregister_all_callbacks( const cci_originator& orig ); -``` - -returning `true` if any *callback* was unregistered. The *originator* might be retrieved from **`get_originator`** on the *parameter* object or *parameter handles*; for *handles* a possible shortcut is **`cci_broker_handle::get_originator`** since all *parameter -handles* created from a *broker handle* share its *originator*. - -##### Testing for callbacks - -``` -bool has_callbacks() const; -``` - -Returns `true` if any *callbacks* are registered against the *parameter*, regardless of the *originator* or phase. - -#### 5.4.2.9 Parameter handle management - -``` -cci_param_untyped_handle create_param_handle( const cci_originator& originator ) const; -``` - -Creates and returns a *handle*, as described in [5.6.3](#563-cci_param_untyped_handle) for the *parameter*. The *handle*'s *originator* is set to the given *originator*. The returned *handle* is certain to be valid and remains so until the *parameter* is destroyed. - -The explicit decoupling of *parameter* object and *handle* lifetimes requires that a list of (*parameter*, *handle*) pairs is maintained, -such that destroying a *parameter shall* invalidate all *handles* to it. The CCI design places this responsibility upon the *parameter* at the API level (the *implementation* may delegate it beyond this), which requires these methods to add and remove *handles*. They are -private and provided solely for the **`cci_param_untyped_handle`** *implementation's* use. - -#### 5.4.2.10 Destructor - -``` -~cci_param_if(); -``` - -This destructor *shall* be overridden by subclass to address: - - discarding of all registered *callbacks*. - - invalidation of any **`cci_param_[un]typed_handle`** pointing to this *parameter*, after which their **`is_valid`** method returns `false` and most operations on the *handle* will fail with an error report. - - unregistration of the *parameter* name, meaning that a subsequently created *parameter* with the same hierarchical name *shall* be created without having a unique suffix appended. - - removal from the broker, with the *preset value* (if any) being marked as unconsumed. - -### 5.4.3 cci_broker_if - -The *broker* interface provides *parameter* un/registration, name-based *parameter* lookup and *value* retrieval, *preset value* -management, and *parameter* creation/destruction callbacks. A default *implementation* is provided by **`cci_utils::consuming_broker`** -described in [5.7.3](#573-reference-brokers). *Brokers* are typically accessed through a **`cci_broker_handle`** (see [5.7.1](#571-cci_broker_handle)) obtained from **`cci_get_broker`** (see [5.7.2](#572-cci_broker_manager)). - -``` -class cci_broker_if -{ - public: - // Broker properties - virtual const char* name() const = 0; virtual bool is_global_broker() const = 0; - - // Parameter access - virtual cci_param_untyped_handle get_param_handle( - const std::string& parname, const cci_originator& originator ) const = 0; - virtual cci_originator get_value_origin( - const std::string& parname ) const = 0; - virtual cci_value get_cci_value( const std::string& parname, - const cci_originator& originator = cci_originator() ) const = 0; - - // Bulk parameter access - virtual std::vector get_param_handles( - const cci_originator& originator = cci_originator() ) const = 0; - virtual cci_param_range get_param_handles( - cci_param_predicate& pred, const cci_originator& originator ) const = 0; - - // Parameter initialization - virtual bool has_preset_value( const std::string& parname ) const = 0; - virtual void set_preset_cci_value( - const std::string& parname, const cci_value& cci_value, - const cci_originator& originator ) = 0; - virtual cci_value get_preset_cci_value( const std::string& parname ) const = 0; - virtual cci_originator get_preset_value_origin( - const std::string& parname ) const = 0; - virtual void lock_preset_value( const std::string& parname ) = 0; - virtual std::vector get_unconsumed_preset_values() const = 0; - virtual cci_preset_value_range get_unconsumed_preset_values( - const cci_preset_value_predicate& pred ) const = 0; - virtual void ignore_unconsumed_preset_values( - const cci_preset_value_predicate& pred ) = 0; - - // Handle creation - virtual cci_broker_handle create_broker_handle( - const cci_originator& originator = cci_originator() ) = 0; - - // Callbacks - virtual cci_param_create_callback_handle register_create_callback( - const cci_param_create_callback&, const cci_originator& ) = 0; - virtual bool unregister_create_callback( - const cci_param_create_callback_handle&, const cci_originator& ) = 0; - virtual cci_param_destroy_callback_handle register_destroy_callback( - const cci_param_destroy_callback&, const cci_originator& ) = 0; - virtual bool unregister_destroy_callback( - const cci_param_destroy_callback_handle&, const cci_originator& ) = 0; - virtual bool unregister_all_callbacks( const cci_originator& ) = 0; - virtual bool has_callbacks() const = 0; - - // Parameter un/registration - virtual void add_param( cci_param_if* par ) = 0; - virtual void remove_param( cci_param_if* par ) = 0; - - protected: - virtual ~cci_broker_if(); - - // Disabled - cci_broker_if( cci_broker_if&& ) = delete; - cci_broker_if( const cci_broker_if& ) = delete; - cci_broker_if& operator=( cci_broker_if&& ) = delete; - cci_broker_if& operator=( const cci_broker_if& ) = delete; -}; -``` - -#### 5.4.3.1 Broker properties - -A *broker* is constructed with a name, which is made unique if necessary by **`cci_gen_unique_name`** (see [5.9](#59-name-support-functions)). *Broker* names are provided for identification which is helpful for debug and logging. - -``` -const std::string& name(); -``` - -Returns the broker's name. - -``` -bool is_global_broker() const; -``` - -Returns `true` for the *global broker*, `false` otherwise. - -#### 5.4.3.2 Individual parameter access - -A *broker* provides *handles* to access the *parameters* it manages. - -``` -cci_param_untyped_handle get_param_handle( - const std::string& parname, const cci_originator& originator ) const = 0; -``` - -Given the full hierarchical name of a *parameter* registered on this *broker* and the *originator* to record as the source of writes -through the *handle*, it returns a newly-created *handle* for the *parameter*. If the name doesn’t match any *parameter* then the *handle* is explicitly invalid. - -*Example:* - -``` -cci_param p( "p1", 42 ); // CCI_RELATIVE_NAME -cci_param_handle ph = broker.get_param_handle( "p1" ); // get uses CCI_ABSOLUTE_NAME -sc_assert( !ph.is_valid() ); -ph = broker.get_param_handle( "testmod.p1" ); -sc_assert( ph.is_valid() ); -``` - -For convenience and potential efficiency a small subset of the -*parameter* functionality is made directly available: - -``` -cci_originator get_value_origin( const std::string& parname ) const = 0; -cci_value get_cci_value( const std::string& parname, - const cci_originator& originator ) const = 0; -``` - -**`get_value_origin`** returns a copy of the *originator* that most recently set the *parameter*’s *value*, or if the *parameter* is not currently registered then an *originator* for which **`is_unknown`** (see [5.4.1.3](#5413-identity)) is `true`. - -#### 5.4.3.3 Bulk parameter access - -Retrieves a vector of *handles*, created for the given *originator*, to all *parameters* registered with the *broker* (and in the case of -*local brokers*, also those registered on the parent brokers), optionally interposing a filtering predicate such that iterating -through the vector skips past the *handles* that the predicate rejects: - -``` -std::vector get_param_handles( - const cci_originator& originator = cci_originator() ) const; -cci_param_range get_param_handles( - cci_param_predicate& pred, const cci_originator& originator ) const; -``` - -Note that generating a *handle* for every *parameter* (and subsequently removing them when the vector is destroyed) may be -expensive. Note also that the predicate form doesn’t avoid this expense – in the following example *handles* for *parameters* “b” and “c” are still generated, merely hidden by the range iterator. - -*Example:* - -``` -cci_param pa( "a", 1 ); -cci_param pb( "b", "foo" ); -cci_param pc( "c", 2.0 ); -cci_param pd( "d", 3 ); -// Simple predicate accepting only numeric params -cci_param_predicate pred([]( const cci_param_handle&p ) -{ - return p.get_data_category() == CCI_NUMBER_PARAM; -} ); - -cci_param_range r = broker.get_param_handles( pred ); -for( auto p : r ) - cout << p.name() << endl; // lists "a" and "d" -``` - -#### 5.4.3.4 Parameter initialization - -A newly-created *parameter* has the *default value*, with which it was constructed. This *may* be supplanted by a *preset value*, supplied by the *broker* to which the *parameter* is added. *Parameters* are re-initialized in this same way, with the *preset value* having precedence over the *default value*, when **`reset`**. - -``` -virtual bool has_preset_value( const std::string& parname ) const = 0; -``` - -Indicates whether the *broker* has a *preset value* for the specified *parameter*. - -``` -void set_preset_cci_value( - const std::string& parname, const cci_value& cci_value, - const cci_originator& originator ); -``` - -Sets the *preset value* for the *parameter* with the given full hierarchical name. Whenever a *parameter* of that name is added to the -*broker* its *value* will be set to the given *preset value* and the **`value_origin`** to the given *originator*. Updating the *preset -value* after *parameter* construction is permitted and will have effect on subsequent calls to **`reset`**. - -Note that the **`cci_value`** added *shall* support `template` **`get`** for the **`cci_param`**`` -being added or a **`CCI_VALUE_FAILURE`** error will be reported. In the following example the value of qNum will be displayed as `17.0` -(small int successfully coerced as double) but the construction of qStr will report **`CCI_VALUE_FAILURE`** and depending upon -sc_report_handler configuration, either throw the error report or proceed without applying the configuration. - -*Example:* - -``` -cci_get_broker().set_preset_cci_value( "m.q", cci_value(17) ); -{ - cci_param qNum( "q", 2.0, "desc", CCI_RELATIVE_NAME ); - cout << "q val=" << qNum.get_cci_value() << endl; -} -{ - cci_param qStr( "q", "fish", "desc", CCI_RELATIVE_NAME ); - cout << "q val=" << qStr.get_cci_value() << endl; -} -``` - -The *parameter* name is used after it has been made unique, meaning that if two *parameters* with the same hierarchical name are added -only the first will receive the *preset value* as the second will have been suffixed with a sequence number. The *preset value may* be -changed by further calls to **`set_preset_cci_value`** but *cannot* be removed. - -``` -cci_value get_preset_cci_value( const std::string& parname ) const; -``` - -Returns the *preset value* for the *parameter* with the given full hierarchical name, or a null **`cci_value`** if no *preset value* is defined. Note that a null **`cci_value`** could in fact be the configured *preset value* for a *parameter*. - -``` -cci_originator get_preset_value_origin( const std::string& parname ) const; -``` - -Returns a copy of the *originator* that most recently set the *parameter*’s *preset value*, or if no *preset value* exists then an -*originator* for which **`is_unknown`** (see [5.4.1.3](#5413-identity)) is `true`. - -``` -void lock_preset_value( const std::string& parname ); -``` - -If the *preset value* for the *parameter* with the given full hierarchical name is locked then attempts to **`set_preset_cci_value`** for it will be rejected with a **`set_param_failed`** error. It *may* be locked before any **`set_preset_cci_value`** *call*, meaning that no *preset value can* be defined and the *default value* will be in effect. A locked *preset value cannot* be unlocked. - -##### Enumerating unconsumed preset values - -A *preset value* that is configured but not “consumed” by being assigned to a created *parameter* may indicate a configuration error -such as incorrect hierarchical names or an expected module not being instantiated. A tool or log file might provide such information to the user. - -``` -std::vector get_unconsumed_preset_values() const; -``` - -Returns a list of all *preset values* not used for the current set of *parameters*, as pairs of (*parameter* name, *preset* **`cci_value`**). A *preset value* is marked as used when a *parameter* of that name is constructed and is marked again as unused when that *parameter* is destroyed. The most useful time to report unconsumed *preset values* is typically after the end of elaboration. - -The list of unconsumed *preset values may* be filtered by a predicate, for example to remove expected entries: - -``` -cci_preset_value_range get_unconsumed_preset_values( - const cci_preset_value_predicate& pred ) const; -``` - -Returns a range iterator for the list of unconsumed *preset values*, which filters the iteration functions by the given predicate -*callback*. The predicate is presented with `std::pair` and -returns `false` to skip (suppress) the *preset*. In the following example, *presets* for a test module are ignored by checking for a -hierarchy level named “testmod”. - -*Example:* - -``` -auto uncon = cci_get_broker().get_unconsumed_preset_values( - []( const std::pair& iv ) - { - return iv.first.find( "testmod." ) == string::npos; } - ); -for( auto v : uncon ) -{ - SC_REPORT_INFO( "Unconsumed preset: ", v.first ); -} -``` - -The provision of the filtering predicate and the retrieval of the list of unconsumed *preset values may* be performed as separate operations: - -``` -void ignore_unconsumed_preset_values( - const cci_preset_value_predicate& pred ); -``` - -Applies the given filtering predicate to the current set of unconsumed *preset values* and accumulates the matches from all such calls in a list of presets to be filtered (omitted) from the results of subsequent calls to **`get_unconsumed_preset_values`**. Because the -predicate is applied immediately it is advisable that the complete set of *preset values* is configured before modules and *parameters* are initialized, i.e. a suitable workflow is: - 1. Create a (possibly *local*) *broker*. - 2. Initialize *preset values* through **`cci_broker_[if|handle]::set_preset_cci_value`**. - 3. As part of defining *parameters*, modules use **`cci_broker_handle::ignore_unconsumed_preset_values`** to add matching (currently unconsumed) presets to the suppression list. - 4. Later (or at end of simulation) fetch the list of interesting *preset values* that remain unconsumed through **`cci_broker_handle::get_unconsumed_preset_values`**. - -#### 5.4.3.5 Create handle - -``` -cci_broker_handle create_broker_handle( const cci_originator& originator = cci_originator() ); -``` - -Return a newly-created and initialized *handle* for the broker. The given *originator* is used for operations that ultimately result in -attributable changes, for example setting a *preset value* or creating a *parameter handle*. - -#### 5.4.3.6 Broker callbacks - -*Callback* functions *may* be registered on a *broker* for the creation and destruction of *parameters* (strictly, this is the -addition and removal of the *parameters* from the broker, however this occurs solely in the context of creating and destroying *parameters*). The distinction is only important because it means that there is no mechanism for being notified of all *parameter* creations, so *local brokers* remain truly local. - -*Callbacks* are invoked in order of registration. If a *callback* throws an exception (including as part of error reporting) then this -immediately propagates through the cci framework code without further *callbacks* being invoked and leaving all existing state modifications intact. If *callbacks* are used to update complex state then -consideration *should* be given to at least providing a basic exception guarantee (that system invariants are not violated). - -#### 5.4.3.7 Creation callbacks - -``` -cci_param_create_callback_handle register_create_callback( - const cci_param_create_callback&, const cci_originator& ); -``` - -Registers a *callback* function of the signature: `void` **`callback`**`(const `**`cci_param_untyped_handle`**`& ph)`, paired with -the given *originator*. The returned **`cci_param_create_callback_handle`** is used to unregister the *callback*. - -Creation *callbacks* are invoked from within the **`cci_param_typed`** constructor as almost the final action. This means that the *parameter handle* is functional, but that any further-*derived* class has not been constructed (this will only be problematic if the -**`cci_param_typed`** is sub-classed, then from the *callback* `dynamic_cast` will fail). If the *callback* throws an -exception, either directly or through `sc_report_handler::report`, then the *parameter* construction is unwound without running -destruction *callbacks*. - -``` -bool unregister_create_callback( - const cci_param_create_callback_handle&, const cci_originator& orig ); -``` - -Given both the *handle* returned by registering a *callback* through **`register_create_callback`** and the same *originator* -with which the registration was made, it unregisters the *callback* and returns `true`. - -#### 5.4.3.8 Destruction callbacks - -``` -cci_param_destroy_callback_handle register_destroy_callback( -const cci_param_destroy_callback&, const cci_originator& orig ) = 0; -``` - -Registers a *callback* function of the signature: `void `**`callback`**`(const `**`cci_param_untyped_handle`**`& ph)`. The returned -**`cci_param_destroy_callback_handle`** is used to unregister the *callback*. - -Destruction *callbacks* are invoked with the *parameter* still fully constructed and registered with the *broker*. - -Since destruction *callbacks* are invoked in the context of *parameter* destruction, exceptions *should* be avoided but are not -prohibited. The behavior in such a case will be defined by the **`cci`** *implementation* and may result in `std::terminate`. - -``` -bool unregister_destroy_callback( - const cci_param_destroy_callback_handle&, const cci_originator& ) = 0; -``` - -Given the *handle* returned by registering a *callback* through **`register_destroy_callback`** it unregisters the *callback* -and returns `true`. - -#### 5.4.3.9 Utilities - -``` -bool unregister_all_callbacks( const cci_originator& orig ) = 0; -``` - -Unregisters all creation and destruction *callbacks* registered with the given **`cci_originator`**. Returns `true` if any *callbacks* were unregistered. - -``` -bool has_callbacks() const = 0; -``` - -Returns `true` if any creation or destruction *callbacks* are currently registered with this broker. - -#### 5.4.3.10 Parameter registration - -``` -virtual void add_param( cci_param_if* par ) = 0; -virtual void remove_param( cci_param_if* par ) = 0; -``` - -These *should* only be *called from parameter implementations* and facilitate registering and unregistering with the *broker*. - -#### 5.4.3.11 Destructor - -``` -~cci_broker_if(); -``` - -The destructor is protected to reserve destruction for the owner of the *broker*. This is necessary since there is no provision for -gracefully handling dependent objects such as **`cci_broker_handle`** (unlike the relationship between **`cci_param_if`** and -**`cci_param_[un]typed_handle`** where the lifetimes are explicitly decoupled). - -An implementation of the destructor *shall* invoke **`cci_abort`** if the *broker* still has registered *parameters*, in order to prevent -subsequent erroneous behavior. It follows that applications *should* not destroy a *broker* which has registered *parameters*. - -NOTE---In practice employing a common scoping mechanism for both *local brokers* and their *parameters should* avoid problems with mismatched lifetimes; for example making both the *broker* and the *parameters* member data of a module. -{:.note} - -## 5.5 Variant type parameter values - -It *shall* be possible to examine and modify configuration *parameter -values* of unknown and arbitrarily complex types. - -### 5.5.1 cci_value_category - -The enumeration **`cci_value_category`** *shall* define the basic data types that *shall* be used as building blocks to compose variant type *parameter values*. - -``` -enum cci_value_category { - CCI_NULL_VALUE = 0, - CCI_BOOL_VALUE, - CCI_INTEGRAL_VALUE, - CCI_REAL_VALUE, - CCI_STRING_VALUE, - CCI_LIST_VALUE, - CCI_OTHER_VALUE -}; -``` - - - **`CCI_NULL_VALUE`** – no data type, e.g. a variant object with no explicit initialization. - - **`CCI_BOOL_VALUE`** – C++ `bool` type. - - **`CCI_INTEGRAL_VALUE`** – integer of up to 64 bits, i.e. representable as `int64_t` or `uint64_t`. - - **`CCI_REAL_VALUE`** – floating point value, represented as C++ `double`. - - **`CCI_STRING_VALUE`** – C++ null-terminated string. - - **`CCI_LIST_VALUE`** – a list of values, each of which *may* be of any **`cci_value_category`**. - - **`CCI_OTHER_VALUE`** – a type not matching any other category, including value-maps. - -### 5.5.2 cci_value - -The **`cci_value`** class *shall* provide a variant type for exchanging configuration *parameter values*. The following types are supported: - - The familiar C++ data types referred to by **`cci_value_category`** are supported, as are restricted types that *can* be coerced into them, such as `int32_t`, `int16_t` and `int8_t`. - - Common SystemC data types: `sc_core::sc_time`, from `sc_dt::sc_logic`, `sc_int_base`, `sc_uint_base`, `sc_signed`, `sc_unsigned`, `sc_bv_base`, `sc_lv_base`. - - User-specific data types, supported by implementing the helper template class **`cci_value_converter`**`` (which is also the mechanism by which the C++ and SystemC data types are supported). -- C++ arrays and `std::vector<>` of any supported data type, converting to a **`cci_value_list`**. -- Lists (vectors) of **`cci_value`**, represented as **`cci_value_list`**. -- String-keyed maps of **`cci_value`**, represented as **`cci_value_map`**. - -Because lists and maps contain **`cci_value`** objects they are explicitly heterogeneous and *can* arbitrarily mix data types, -including nesting **`cci_value_list`** and **`cci_value_map`** to arbitrary depths. - -Objects of this class have strict *value* semantics, i.e. each *value* represents a distinct object. Due to hierarchical nature of the data structure, values embedded somewhere in the list or map are referenced by dedicated reference objects (*`cci_value_cref`†*, -*`cci_value_ref`†*, and their specialized variants for strings, lists and maps), with or without constness. - -The **`cci_value::reference`** and **`cci_value::const_reference`** classes are defined as modifier and accessor interface classes, such that a **`cci_value`** instance *shall* be transparently used where those interface classes are expected. Having them form base classes for **`cci_value`** is a suggested approach. - -#### 5.5.2.1 Class definition - -``` -class cci_value : public implementation-defined -{ - typedef cci_value this_type; - public: - /// reference to a constant value - typedef implementation-defined const_reference; - /// reference to a mutable value - typedef implementation-defined reference; - /// reference to a constant string value - typedef implementation-defined const_string_reference; - /// reference to a mutable string value - typedef implementation-defined string_reference; - /// reference to a constant list value - typedef implementation-defined const_list_reference; - /// reference to a mutable list value - typedef implementation-defined list_reference; - /// reference to a constant map value - typedef implementation-defined const_map_reference; - /// reference to a mutable map value - typedef implementation-defined map_reference; - - // Constructors and destructor - cci_value(); - template - explicit cci_value( T const& src, typename cci_value_converter::type* = 0 ); - - cci_value( this_type const& that ); - cci_value( const_reference that ); - cci_value( this_type&& that ); cci_value( cci_value_list&& that ); - cci_value( cci_value_map&& that ); - - this_type& operator=( this_type const& ); - this_type& operator=( const_reference ); - - this_type& operator=( this_type&& ); - this_type& operator=( cci_value_list&& ); - this_type& operator=( cci_value_map&& ); - - friend void swap( this_type& a, this_type& b ); - void swap( reference that ); - void swap( cci_value& that ); - - // Type queries – possibly inherited from "const_reference" - cci_value_category category() const; - bool is_null() const; - bool is_bool() const; - bool is_false() const; - bool is_true() const; - bool is_number() const; - bool is_int() const; - bool is_uint() const; - bool is_int64() const; - bool is_uint64() const; - bool is_double() const; - bool is_string() const; - bool is_map() const; - bool is_list() const; - bool is_same( const_reference that ) const; - - // Set basic value – possibly inherited from "reference" - reference set_null(); - reference set_bool( bool v ); - reference set_int( int v ); - reference set_uint( unsigned v ); - reference set_int64( int64 v ); - reference set_uint64( uint64 v ); - reference set_double( double v ); - string_reference set_string( const char* s ); - string_reference set_string( const_string_reference s ); - string_reference set_string( const std::string& s ); - list_reference set_list(); - map_reference set_map(); - - // Set arbitrarily typed value – possibly inherited from "reference" - template< typename T > - bool try_set( T const& dst, CCI_VALUE_ENABLE_IF_TRAITS_(T) ); - template< typename T > - reference set( T const& v, CCI_VALUE_ENABLE_IF_TRAITS_(T) ); - - // Get basic value – possibly inherited from "const_reference" - bool get_bool() const; - int get_int() const; - unsigned get_uint() const; - int64 get_int64() const; - uint64 get_uint64() const; - double get_double() const; - double get_number() const; - - // Get arbitrarily typed value - template - bool try_get( T& dst ) const; - template - (T) get() const; - - // Access as complex value – possibly inherited - const_string_reference get_string() const; - string_reference get_string(); - const_list_reference get_list() const; - list_reference get_list(); - const_map_reference get_map() const; - map_reference get_map(); - - // JSON (de)serialization – possibly inherited - static cci_value from_json( std::string const& json ); - std::string to_json() const; - - // Friend functions - friend std::istream& operator>>( std::istream& is, cci_value& v ); -}; -``` - -#### 5.5.2.2 Constructors and destructor - -``` -cci_value(); -``` - -A default-constructed *value* has the **`cci_value_category`** of **`CCI_NULL_VALUE`**. - -``` -template -explicit cci_value( T const& src ); -``` - -Construction from a source data type internalizes the *value* through **`cci_value_converter`**``::**`pack`**. For the conventional data types these delegate to the appropriate explicit setter functions. - -``` -cci_value( cci_value const& that ); -cci_value( const_reference that ); -``` - -Copy-construction, overloaded both for a sibling instance and the **`const_reference`** accessor interface. - -``` -cci_value( cci_value&& that ); -cci_value( cci_value_list&& that ); -cci_value( cci_value_map&& that ); -``` - -Move-construction, acquiring the *value* of `that` and leaving that freshly initialized. The list and map overloads correctly acquire the container types to ensure that the source is left initialized empty and of the correct type. - -An *implementation* may provide similar semantics when compiled for C++ versions prior to C++11, for example through additional methods. - -``` -~cci_value(); -``` - -Frees the associated value storage. Because reference objects obtained from a **`cci_value`** are constructed as copies and subsequent -assignment to them updates their own storage rather than aliasing the source's storage, they do not pose a dangling-reference hazard. The -following example shows that `m2` going out of scope does not invalidate the **`map_reference`** `p1` assigned from it, and that `p1` continues to refer to the **`cci_value`** `m1` that it was constructed from. - -*Example:* - -``` -cci_value m1; -cci_value::map_reference p1 = m1.set_map(); -p1.push_entry( "1", "a" ); // m1 == { ["1", "a"] } -{ - cci_value m2; - p1 = m2.set_map(); // m1 == { }, m2 = { } - p1.push_entry( "2", "b" ); // m1 == { ["2", "b"] }, m2 == { } -} -p1.push_entry( "3", "c" ); // m1 == { ["2", "b"], ["3", "c"] } -``` - -#### 5.5.2.3 Swap functions - -``` -void swap( cci_value& that ); -void swap( reference that ); -cci_value move(); -``` - -The **`swap`** functions exchange the *value* and type of `this` object with that of the supplied **`cci_value`** argument in an exception- and error-report-safe manner. The **`move`** function returns a **`cci_value`** which has taken ownership of `this` object's *value*, with `this` object being reinitialized without an explicit *value*, i.e. equivalent to the state created by **`set_null`**. - -NOTE---These functions are intended to support efficient operations with C++ standard container classes and algorithms. -{:.note} - -#### 5.5.2.4 Type queries - -``` -cci_value_category category() const; -``` - -Returns the basic data type. - -``` -bool is_null() const; -bool is_bool() const; -bool is_number() const; -bool is_int() const; -bool is_uint() const; -bool is_int64() const; -bool is_uint64() const; -bool is_double() const; -bool is_string() const; -bool is_map() const; -bool is_list() const; -``` - -Return `true` if the current *value can* be retrieved as the specified type, or *cannot* be retrieved in the case of **`is_null`**. This depends on the data type and in the case of integers also whether the current *value can* be contained by such an integer type. - -*Example:* - -``` -cci_value v( 7 ); -sc_assert( v.is_int() && v.is_uint() && v.is_int64() && v.is_uint64() ); -v = cci_value( 1UL << 34 ); -sc_assert( !v.is_int() && !v.is_uint() && v.is_int64() && v.is_uint64() ); -v = cci_value( 1UL << 63 ); -sc_assert( !v.is_int() && !v.is_uint() && !v.is_int64() && v.is_uint64() ); -``` - -In contrast, coercion between `string`, `integer`, and `double` types is not supported, even where no loss of precision would occur. - -*Example:* - -``` -cci_value v( 1 ); -sc_assert( v.is_int() && !v.is_double() && !v.is_string() ); -v = cci_value( 1.0 ); -sc_assert( !v.is_int() && v.is_double() && !v.is_string() ); -v = cci_value( "1" ); -sc_assert( !v.is_int() && !v.is_double() && v.is_string() ); -``` - -Convenience functions combining **`is_bool`** and testing the result of **`get_bool`**: - -``` -bool is_false() const; -bool is_true() const; -``` - -#### 5.5.2.5 Get value - -##### Core types - -Explicitly named functions get the core types by value: - -``` -bool get_bool() const; -int get_int() const; -unsigned get_uint() const; -int64 get_int64() const; -uint64 get_uint64() const; -double get_double() const; -double get_number() const; // synonym for get_double() -``` - -In general an error is reported unless the type would be identified by an `is_TYPE` query, i.e. a safe idiom is: - -``` -if( cv.is_TYPE() ) - value = cv.get_TYPE(); -``` - -However getting a small integer as a larger one is supported: - -``` -if( cv.is_int() ) - value = cv.get_int64(); -``` - -An *implementation may* support getting an integer as a double but this may result in loss of precision. - -*Example:* - -``` -cv.set_uint64( (1UL << 63 ) | 0 ); -sc_assert( cv.get_uint64() == uint64_t( cv.get_double() ) ); -cv.set_uint64( (1UL << 63 ) | 1 ); -sc_assert( cv.get_uint64() != uint64_t( cv.get_double() ) ); -``` - -##### Extended and user-defined types - -Other *value* types are retrieved with the type-templated **`get`** function: - -``` -template -typename cci_value_converter::type get() const; -``` - -This uses the **`cci_value_converter`**`` to extract the stored *value* and convert it to an object of type T, which is returned by value. If the *value* cannot be converted, for example because it is of a different type, then a **`cci_value_failure`** (see [5.8](#58-error-reporting)) error is reported. The validation and conversion of each type `T` is defined by the -**`cci_value_converter`**`` implementation. Converters are provided by the CCI library for the supported data types listed in -[5.5.2](#552-cci_value) If **`get`** is used with a user-defined type that lacks a **`cci_value_converter`**`` definition then linker errors will occur. - -``` -template -bool try_get( T& dst ) const; // omitting additional type argument for C++ selection logic -``` - -A conditional form of **`get`**, which upon success updates the *typed* reference argument and returns `true`. - -*Example:* - -``` -sc_core::sc_time end; -if( !endVal.try_get( end ) ) - return ENotFinished; -// Calculate total running time; if end was defined then start must be defined -// so can use unconditional get. -sc_core::sc_time start = startVal.get(); -``` - -##### Reference types - -The getters for the structured data types (string, list, and map) return by reference: - -``` -const_string_reference get_string() const; -string_reference get_string(); -const_list_reference get_list() const; -list_reference get_list(); -const_map_reference get_map() const; -map_reference get_map(); -``` - -As would be expected of reference types, they share the common *value*. - -*Example:* - -``` -cci_value val; -val.set_list(); -cci_value::list_reference lr1 = val.get_list(); -lr1.push_back( 1 ); -sc_assert( lr1.size() == 1 ); -cci_value::list_reference lr2 = val.get_list(); -lr2.push_back( 2 ); -sc_assert( lr1.size() == 2 ); -``` - -A natural consequence of this is that changing the *underlying data -type* invalidates the references. - -*Example:* - -``` -cci_value val; -val.set_list(); -cci_value::list_reference lr1 = val.get_list(); -val.set_null(); -sc_assert( lr1.size() == 0 ); // throws a RAPIDJSON_ASSERT exception -``` - -#### 5.5.2.6 Set value - -*Value* setters: - 1. Set the *value* type. - 2. Initialize to the passed *value*, where supported. - 3. Return a suitable reference; for simple types a **`cci_value::const_reference`** for the *value* object, for structured types - (string, list, map) the matching type reference class (**`string_reference`**, **`list_reference`**, **`map_reference`** - respectively). - -``` -reference set_null(); -reference set_bool( bool v ); -reference set_int( int v ); -reference set_uint( unsigned v ); -reference set_int64( int64 v ); -reference set_uint64( uint64 v ); -reference set_double( double v ); -string_reference set_string( const char* s ); -string_reference set_string( const_string_reference s ); -string_reference set_string( const std::string& s ); -list_reference set_list(); -map_reference set_map(); -template< typename T > -bool try_set( T const& dst ); // omitting additional type argument for C++ selection logic -template< typename T > -reference set( T const& v ); // omitting additional type argument for C++ selection logic -``` - -#### 5.5.2.7 Identity query - -``` -bool is_same( const_reference that ) const; -``` - -Returns `true` if both this *value* and the given reference are for the same underlying *value* object, as opposed to merely having values that evaluate according to operator==. - -#### 5.5.2.8 JSON (de) serialization - -``` -std::string to_json() const; -``` - -Returns a JSON description of the value. For custom types this will typically be a list or a map (as specified by the **`cci_value_converter`**`` *implementation*). - -``` -static cci_value from_json( std::string const& json ); -``` - -Given a JSON description of the value, returns a new **`cci_value`** initialized with the value. Reports a *value* error if the JSON -description is invalid. - -### 5.5.3 cci_value_list - -A **`cci_value_list`** is conceptually a vector of **`cci_value`** objects, where each element remains a variant type, i.e. the *value* types placed in the vector *may* be heterogeneous. - -*Example:* - -``` -cci_value_list val; -val.push_back( 7 ).push_back( "fish" ); -``` - -The **`cci_value_list`** type offers `const` and modifiable reference classes along with the instantiable class. The reference classes -provide container interfaces modeled on the C++ standard library such as iterators, while the instantiable class provides the expected -construction and assignment methods. - -``` -class cci_value_list : public implementation-defined -{ - public: - typedef cci_value_list this_type; - typedef implementation-defined const_reference; - typedef implementation-defined reference; - typedef implementation-defined proxy_ptr; - - typedef size_t size_type; - typedef cci_value_iterator iterator; - typedef cci_value_iterator const_iterator; - typedef std::reverse_iterator reverse_iterator; - typedef std::reverse_iterator const_reverse_iterator; - - // "const_reference" members - bool empty() const; - size_type size() const; - size_type capacity() const; - - const_reference operator[]( size_type index ) const; - const_reference at( size_type index ) const; - - const_reference front() const; - const_reference back() const; - - const_iterator cbegin() const; - const_iterator cend() const; - - const_iterator begin() const; - const_iterator end() const; - - const_reverse_iterator rbegin() const; - const_reverse_iterator rend() const; - - const_reverse_iterator crbegin() const; - const_reverse_iterator crend() const; - - proxy_ptr operator&() const { return proxy_ptr(*this); } - - // "reference" (modifable) members - this_type operator=( this_type const& ); - this_type operator=( base_type const& ); - - cci_value move(); - - void swap( this_type& ); - friend void swap( this_type a, this_type b ); - - cci_value_list_ref† reserve( size_type ); - cci_value_list_ref† clear(); - - reference operator[]( size_type index ); - reference at( size_type index ); - - reference front() - reference back() - iterator begin(); - iterator end(); - reverse_iterator rbegin() - reverse_iterator rend() - - cci_value_list_ref† push_back( const_reference v ); - cci_value_list_ref† push_back( cci_value&& v ); - template - cci_value_list_ref† push_back( const T& v ); //FIXME: one argument? - - iterator insert( const_iterator pos, const_reference value ); - iterator insert( const_iterator pos, size_type count, const_reference value ); - template< class InputIt > - iterator insert( const_iterator pos, InputIt first, InputIt last ); - - iterator erase( const_iterator pos ); - iterator erase( const_iterator first, const_iterator last ); - - void pop_back(); - - proxy_ptr operator&() const { return proxy_ptr(*this); } - - // Concrete class - cci_value_list(); - cci_value_list( this_type const& ); - cci_value_list( const_reference ); - cci_value_list( this_type&& ); - this_type& operator=( this_type const& ); - this_type& operator=( const_reference ); - this_type& operator=( this_type&& ); - friend void swap( this_type& a, this_type& b ) { a.swap(b); } - void swap( reference that ) { reference::swap( that ); } - void swap( this_type& ); - - ~cci_value_list(); - const cci_value_list* operator&() const { return this; } - cci_value_list* operator&() { return this; } -}; -``` - -### 5.5.4 cci_value_map - -A **`cci_value_map`** is conceptually a map of string keys to **`cci_value`** objects, where each element remains a variant type, i.e. the value types placed in the vector may be heterogeneous. - -*Example:* - -``` -cci_value_map vmap; -vmap["foo"] = cci_value( 7 ); -vmap["bar"] = cci_value( sc_core::sc_time_stamp() ); -``` - -The **`cci_value_map`** type offers `const` and modifiable reference classes along with the instantiable class. The reference classes provide container interfaces modelled on the C++ standard library such as iterators, while the instantiable class provides the expected construction and assignment methods. - -``` -class cci_value_map : public implementation-defined -{ - public: - typdedef cci_value_map this_type; - typedef implementation-defined const_reference; - typedef implementation-defined reference; - typedef implementation-defined proxy_ptr; - - typedef size_t size_type; - typedef cci_value_iterator iterator; - typedef cci_value_iterator const_iterator; - typedef std::reverse_iterator reverse_iterator; - typedef std::reverse_iterator const_reverse_iterator; - - // "const_reference" members - bool empty() const; - size_type size() const; - bool has_entry( const char* key ) const; - bool has_entry( std::string const& key ) const; - bool has_entry( cci_value_string_cref† key ) const; - - const_reference at( const char* key ) const; - const_reference at( std::string const& key ) const; - - const_iterator cbegin() const; - const_iterator cend() const; - - const_iterator begin() const; - const_iterator end() const; - - const_reverse_iterator rbegin() const; - const_reverse_iterator rend() const; - - const_reverse_iterator crbegin() const; - const_reverse_iterator crend() const; - - const_iterator find( const char* key ) const; - const_iterator find( const std::string& key ) const; - - proxy_ptr operator&() const { return proxy_ptr(*this); } - - // "reference" members - this_type operator=( base_type const& ); - this_type operator=( this_type const& ); - - cci_value move(); - - /// Exchange contents with another map void swap( this_type& ); - friend void swap( this_type a, this_type b ); - this_type clear(); - reference at( const char* key ); - reference at( std::string const& key ); - reference operator[]( const char* key ); - reference operator[]( std::string const& key ); - - iterator begin(); iterator end(); - - reverse_iterator rbegin(); - reverse_iterator rend(); - - iterator find( const char* key ); - iterator find( const std::string& key ); - - this_type push_entry( const char* key, const_reference value ); - this_type push_entry( std::string const& key, const_reference value ); - - this_type push_entry( const char* key, cci_value&& value ); - this_type push_entry( std::string const& key, cci_value&& value ); - - /// Add an arbitrary cci_value_converter enabled value - template - this_type push_entry( const char* key, const T& value ); - template - //FIXME: missing? - - size_type erase( const char* key ); - size_type erase( const std::string& key ); - - iterator erase( const_iterator pos ); - iterator erase( const_iterator first, const_iterator last ); - - proxy_ptr operator&() const { return proxy_ptr(*this); } - - // Concrete class - cci_value_map(); - cci_value_map( this_type const& ); - cci_value_map( const_reference ); - cci_value_map( this_type&& ); - - this_type& operator=( this_type const& ); - this_type& operator=( const_reference ); - this_type& operator=( this_type&& ); - - friend void swap( this_type& a, this_type& b ); - void swap( reference that ); - void swap( this_type& ); - - ~cci_value_map(); - - const cci_value_map* operator&() const { return this; } - cci_value_map* operator&() { return this; } -}; -``` - -#### 5.5.4.1 Element access - -The **`const_map_reference`** interface provides the checked **`at`** function: - -``` -const_reference at( const char* key ) const; -const_reference at( std::string const& key ) const; -``` - -This returns a reference to the **`cci_value`** object at the given index, or reports a *value* error if the index is invalid. The -map_reference interface retains the validity checking but returns a modifiable element reference: - -``` -reference at( const char* key ); -reference at( std::string const& key ); -``` - -and adds array-styled access which inserts new index values: - -``` -reference operator[]( const char* key ); -reference operator[]( std::string const& key ); -``` - -*Example:* - -``` -cci_value_map vmap; -cci_value::map_reference mr( vmap ); -mr["foo"] = cci_value( 1 ); -mr.at( "foo" ) = cci_value( 2 ); -mr.at( "bar" ) = cci_value( 3 ); // reports CCI_VALUE error -``` - -## 5.6 Parameters - -Actual *parameters* are created as instances of **`cci_param_typed`**, which in concert with its base class **`cci_param_untyped`** -implements the **`cci_param_if`** (see [5.4.2](#542-cci_param_if)) interface. As the names suggest the functionality is divided between that common to all *parameter* types and that which depends upon the concrete *value* type. - -### 5.6.1 cci_param_untyped - -Implements much of the parent **`cci_param_if`** interface class and extends it with convenient registration of *untyped callbacks*. The -inherited methods are described in the **`cci_param_if`** interface class and not further detailed here. - -``` -class cci_param_untyped : public cci_param_if -{ - public: - // The pre-read callback phase detailed here; equivalent methods exist for all three phases - cci_callback_untyped_handle register_pre_read_callback( - const cci_param_pre_read_callback_untyped& cb, - cci_untyped_tag = cci_untyped_tag() ); - template - cci_callback_untyped_handle register_pre_read_callback( - cci_param_pre_read_callback_untyped::signature(C::*cb), C* obj, - cci_untyped_tag = cci_untyped_tag() ); - bool unregister_pre_read_callback( const cci_callback_untyped_handle& cb ); - bool unregister_all_callbacks(); -}; -``` - -These additional *callback* registration and unregistration methods provide a convenient veneer; the actual *callback* semantics remain as described in **`cci_param_if`**. - -``` -cci_callback_untyped_handle register_pre_read_callback( - const cci_param_pre_read_callback_untyped& cb, - cci_untyped_tag = cci_untyped_tag() ); -``` - -Register a global function as a pre-read *callback*, using the *parameter*'s *originator* as the *callback originator* (as passed to -the *callback* through the **`cci_param_read_event`** object). The following example uses a static member function. - -*Example:* - -``` -auto cbh = paramUT.register_pre_read_callback( &Logger::static_pre_read_callback ); -``` - -Note that as above the packaging **`cci_param_pre_read_callback_untyped`** object will typically be implicitly constructed simply by passing the pointer to the static/global function. - -``` -template -cci_callback_untyped_handle register_pre_read_callback( - cci_param_pre_read_callback_untyped::signature(C::*cb), C* obj, - cci_untyped_tag = cci_untyped_tag() ); -``` - -Register a member function as a pre-read *callback*, using the *parameter*'s *originator* as the *callback originator* (as passed to -the *callback* through the **`cci_param_read_event`** object). - -*Example:* - -``` -auto cbh = paramUT.register_pre_read_callback( &Logger::member_pre_read_callback, &loggerObject ); -``` - -Once again the packaging **`cci_param_pre_read_callback_untyped`** object will typically be implicitly constructed simply by passing the -pointer to the member function along with a pointer to the instance. - -``` -bool unregister_pre_read_callback( const cci_callback_untyped_handle& cb ); -``` - -Unregister a pre-read *callback*, given its registration *handle*. Returns `true` if successful. A `false` return may diagnose that -unregistration was already performed or that the registration was made from a **`cci_param_untyped_handle`** (although all *callback -handles* have the static type of **`cci_callback_untyped_handle`** it is required that unregistration is made through the same object as the registration). - -``` -bool unregister_all_callbacks(); -``` - -Unregisters all *callbacks* for all four phases (i.e. pre-read, post-read, pre-write, and post-write) that were registered directly -through this *parameter* object. Returns `true` if any *callback* was unregistered. - -### 5.6.2 cci_param_typed - -The concrete instantiable type for all *parameters*, extending **`cci_param_untyped`** with direct access to the *parameter* value. An instance is templated by: - - the data type. The data type *shall* have the following set of - features (note that this set is more extensive than is required - for compatibility with **`cci_value`**, i.e. it is possible to - construct a **`cci_value`** object with a value type that would not - permit construction of a **`cci_param_typed`** object). Given the - value type `VT`: - - default constructor: `VT()` (`DefaultConstructible` in C++ concept terminology). - - copy constructor: `VT(const VT&)` (`CopyConstructible`). - - value type assignment operator: `operator=(const VT&)` (`CopyAssignable`). - - value type equality operator: `operator==(const VT&)` (`EqualityComparable`). - - **`cci_value_converter`**`` defined. - - *value* mutability expressed as **`cci_param_mutable_type`** see ([5.3.1](#531-cci_param_mutable_type)). - -A concise alias of **`cci_param`** is provided for the common case of mutable *parameters*, as seen in these two equivalent definitions: - -``` -cci_param_typed p1( "p1", 0 ); -cci_param p2( "p2", 0 ); -``` - -The inherited methods are described in the **`cci_param_if`** interface class and not further detailed here. - -``` -template -class cci_param_typed : public cci_param_untyped -{ - public: - typedef T value_type; - - // Construction - cci_param_typed( const std::string& name, const value_type& default_value, - const std::string& desc = "", - cci_name_type name_type = CCI_RELATIVE_NAME, - const cci_originator& originator = cci_originator() ); - cci_param_typed( const std::string& name, const cci_value& default_value, - const std::string& desc = "", - cci_name_type name_type = CCI_RELATIVE_NAME, - const cci_originator& originator = cci_originator() ); - cci_param_typed( const std::string& name, const value_type& default_value, - cci_broker_handle private_broker, - const std::string& desc = "", - cci_name_type name_type = CCI_RELATIVE_NAME, - const cci_originator& originator = cci_originator() ); - cci_param_typed( const std::string& name, const cci_value& default_value, - cci_broker_handle private_broker, - const std::string& desc = "", - cci_name_type name_type = CCI_RELATIVE_NAME, - const cci_originator& originator = cci_originator() ); - - // Typed value access - const value_type& get_value() const; - const value_type& get_value( const cci_originator& originator ) const; - operator const value_type& () const; - const value_type& get_default_value() const; - - void set_value( const value_type& value ); - void set_value( const value_type& value, const void* pwd ); - cci_param_typed& operator=( const cci_param_typed& rhs ); - cci_param_typed& operator=( const value_type& rhs ); - bool reset(); - - // For brevity, only the pre-read callbacks are detailed here - cci_callback_untyped_handle register_pre_read_callback( - const cci_param_pre_read_callback_untyped& cb, cci_untyped_tag ); - - template - cci_callback_untyped_handle register_pre_read_callback( - cci_param_pre_read_callback_untyped::signature(C::*cb), - C* obj, cci_untyped_tag ); - - typedef typename cci_param_pre_read_callback::type - cci_param_pre_read_callback_typed; - - cci_callback_untyped_handle register_pre_read_callback( - const cci_param_pre_read_callback_typed& cb, - cci_typed_tag = cci_typed_tag() ); - - template - cci_callback_untyped_handle register_pre_read_callback( - typename cci_param_pre_read_callback_typed::signature(C::*cb), - C* obj, cci_typed_tag = cci_typed_tag() ); - - cci_param_untyped_handle create_param_handle( - const cci_originator& originator ) const; - - private: - const void* get_raw_value( const cci_originator& originator ) const; - const void* get_raw_default_value() const; - void set_raw_value( const void* vp, const void* pwd, - const cci_originator& originator ); - - private: - void preset_cci_value( const cci_value& value, - const cci_originator& originator ) override; -}; - -``` - -#### 5.6.2.1 value_type - -The *underlying data type* that the **`cci_param_typed`** instance was instantiated with is aliased as `value_type`. - -#### 5.6.2.2 Construction - -Four constructors are provided, combining the pairs of (*automatic broker*, explicit *broker*) and the *default value* expressed as (literal value_type, **`cci_value`**). The constructor parameters are: - - **`parameter name`** – *Parameters* are indexed by name, which is - required to be unique (duplicates are suffixed with a number to - ensure this and a warning report issued). - - **`default_value`** – The default value *shall* be explicitly given - rather than taken from value_type's implicit construction, either - as the literal `value_type` or a **`cci_value`**. - - **`description`** – A description of the *parameter* is encouraged, - for example to annotate configuration logs; it defaults to an - empty string. - - **`name_type`** – The name type defaults to **`CCI_RELATIVE_NAME`**, - in which case the *parameter* name is made absolute (or - hierarchical) by prepending it with the name of the enclosing - `sc_module`. - - **`originator`** – The origin of the *default value* and of subsequent - assignments (unless those are made with an explicit *originator*); - by default, an *originator* representing the current `sc_module`. - - **`private_broker`** – A specific *broker* to hold the *parameter*; - if unspecified, the result of **`cci_get_broker`** (see [5.7.2](#572-cci_broker_manager)) is used. - -``` -// Default as literal value_type, current broker -cci_param_typed( const std::string& name, const value_type& default_value, - const std::string& desc = "", - cci_name_type name_type = CCI_RELATIVE_NAME, - const cci_originator& originator = cci_originator() ); - -// Default as cci_value, current broker -cci_param_typed( const std::string& name, const cci_value& default_value, - const std::string& desc = "", - cci_name_type name_type = CCI_RELATIVE_NAME, - const cci_originator& originator = cci_originator() ); - -// Default as literal value_type, explicit broker -cci_param_typed( const std::string& name, const value_type& default_value, - cci_broker_handle private_broker, - const std::string& desc = "", - cci_name_type name_type = CCI_RELATIVE_NAME, - const cci_originator& originator = cci_originator() ); - -// Default as cci_value, explicit broker -cci_param_typed( const std::string& name, const cci_value& default_value, - cci_broker_handle private_broker, - const std::string& desc = "", - cci_name_type name_type = CCI_RELATIVE_NAME, - const cci_originator& originator = cci_originator() ); -``` - -*Parameters shall not* be instantiated as C++ global variables. Global *parameters* are prohibited in order to guarantee that the *global -broker can* be instantiated prior to the instantiation of any *parameters*. - -#### 5.6.2.3 Typed value access - -The *parameter value may* be read and written directly as the value_type. - -``` -const value_type& get_value() const; -operator const value_type& () const; // convenience form of get_value() -``` - -Provides a *typed* reference to the current value. Note that the pre-read and post-read *callbacks* are triggered by the creation of -the reference and not by actually reading the *value*, in contrast to **`get_cci_value`** which takes a copy of the *value*. - -NOTE---To avoid confusion, especially with *callbacks*, it is preferable to dereference the reference immediately rather than -storing it for later use. -{:.note} - -*Example:* - -``` -cci_param p( "p", 3 ); -p.register_post_read_callback( &log_reads ); -const int& rp = p; // log shows value 3 was read -p = 4; -int val_p = rp; // current value of 4 is really "read" -``` - -``` -const value_type& get_default_value() const; -``` - -Provide a *typed* reference to the default value. - -``` -void set_value( const value_type& value ); -void set_value( const value_type& value, const void* pwd ); -``` - -Pre-write *callbacks* are run, then the *parameter value* is copied from the argument, then post-write *callbacks* are run. If a lock -password (`pwd`) is given then the *parameter value shall* both be locked and the lock be with that password or a **`CCI_SET_PARAM_FAILURE`** error report will be issued. - -``` -bool reset(); -``` - -Fulfills the description in **`cci_param_if`** (see [5.4.2.1](#5421-value-and-data-type)). - -#### 5.6.2.4 Raw value access - -Direct *untyped* access to the *parameter value* storage is provided for the **`cci_typed_handle`** *implementation*; consequently these -methods *shall* be private and accessed through `friend`-ship with the *handle* classes. - -``` -const void* get_raw_value( const cci_originator& originator ) const override; -``` - -As with **`cci_value`** and **`value_type`** value queries, pre-read and post-read *callbacks* are executed before the pointer is returned. - -``` -const void* get_raw_default_value() const override; -``` - -Direct *untyped* access to the *default value*. - -``` -void set_raw_value( const void* vp, const void* pwd, const cci_originator& originator ) override; -``` - -Pre-write *callbacks* are run, then the *parameter value* is copied from the vp argument, then post-write *callbacks* are run. The *value -origin* is updated from the given *originator*. If the *parameter* is locked then the correct password *shall* be supplied; if the -*parameter* is not locked then the password *shall* be set to `nullptr`, or a **`CCI_SET_PARAM_FAILURE`** error report will be issued. - -#### 5.6.2.5 Assignment operator - -``` -cci_param_typed& operator=( const value_type& rhs ); -``` - -An instance of the `value_type` *can* be assigned, as a shorthand for calling **`set_value`**(const value_type&). - -``` -cci_param_typed& operator=( const cci_param_typed& rhs ); -``` - -This *parameter value* is set to a copy of the given *parameter*'s value. Incompatible `value_type`s may cause a compilation error or be -reported as a **`CCI_VALUE_FAILURE`**. - -#### 5.6.2.6 Callbacks - -The *callback* support of **`cci_param_untyped`** is extended with *typed callbacks*, which provide direct `value_type` access to the -current and new *parameter* values. The semantics are further described in the **`cci_param_if`** (see [5.4.2.8](#5428-callbacks)). - -*Untyped callbacks shall* be registered through the **`cci_param_typed`** interface by explicitly tagging them as *untyped*: - -``` -void untyped_pre_read_callback( const cci_param_read_event& ev ) { - const cci_value& val = ev.value; -} -... -cci_param_typed p( "p", 1 ); -p.register_pre_read_callback( &untyped_pre_read_callback, cci_untyped_tag() ); -``` - -Typed *callbacks* are implicitly tagged: - -``` -void typed_pre_read_callback( const cci_param_read_event& ev ) { - const int& val = ev.value; -} -... -cci_param_typed p( "p", 1 ); -p.register_pre_read_callback( &typed_pre_read_callback ); -``` - -The sixteen *callback* registration functions are then composed simply from: four access phases (pre-read, post-read, pre-write, and -post-write), two function types (global, member), and two kinds of *value* access (*untyped* via **`cci_value`**, *typed* as value_type). - -### 5.6.3 cci_param_untyped_handle - -*Parameter handles* function as proxies for the *parameter* instances, providing most of the **`cci_param_untyped`** functionality(functionality such as resetting the value, setting the description, and setting metadata is not present, as these are reserved for the -*parameter* owner). They provide a means of reducing coupling in the model to the *parameter* name (and potentially value type). - -The underlying *parameter* instance *can* be destroyed while *handles* remain, however this immediately invalidates the - -*handles* with the following effects: - - **`is_valid`** returns false. - - Calling any delegating method results in an error report. - -Once a *handle* has become invalid it remains forever invalid, even if a *parameter* of that name is recreated; conceptually the *handle* was created from a specific *parameter* instance, not for a *parameter* name (which may be valid at some times and not at other times). - -*Example:* - -``` -auto p = new cci_param( "p", 5 ); -auto h1 = cci_get_broker().get_param_handle( "testmod.p" ); -sc_assert( h1.is_valid() ); -delete p; -sc_assert( !h1.is_valid() ); -p = new cci_param( "p", 10 ); -auto h2 = cci_get_broker().get_param_handle( "testmod.p" ); -sc_assert( h2.is_valid() ); // newly obtained handle functional -sc_assert( !h1.is_valid() ); // original handle for same name still invalid -``` - -#### 5.6.3.1 Class overview - -Handles are created with a specific *originator*, which is used in cases where the **`cci_param_untyped`** interface allows the -*originator* to be specified. For example, setting the *parameter’s value* via a *handle* records the *originator* as the *value’s* -origin: - -``` -auto ph = param.create_param_handle( orig ); -ph.set_cci_value( val1 ); -ph.set_cci_value( val2 ); -``` - -where through the *parameter* interface the *originator* would be specified upon each setting: - -``` -param.set_cci_value( val1, orig ); -param.set_cci_value( val2, orig ); -``` - -Handles have no inherent collation properties and no comparisons are defined. - -``` -class cci_param_untyped_handle -{ - public: - // Constructors - cci_param_untyped_handle( cci_param_if& param, const cci_originator& originator ); - explicit cci_param_untyped_handle( const cci_originator& originator = cci_originator() ); - cci_param_untyped_handle( const cci_param_untyped_handle& param_handle ); - cci_param_untyped_handle( cci_param_untyped_handle&& that ); - - ~cci_param_untyped_handle(); - - // Assignment - cci_param_untyped_handle& operator=( const cci_param_untyped_handle& param_handle ); - cci_param_untyped_handle& operator=( cci_param_untyped_handle&& that ); - - // Handle validity - bool is_valid() const; - void invalidate(); - - cci_originator get_originator() const; - - // Delegated functions - cci_param_data_category get_data_category() const; - const char* name() const; - cci_param_mutable_type get_mutable_type() const; - - std::string get_description() const; - cci_value_map get_metadata() const; - - cci_value get_cci_value() const; - void set_cci_value( const cci_value& val ); - void set_cci_value( const cci_value& val, void* pwd ); - cci_value get_default_cci_value() const; - - bool lock( const void* pwd = nullptr ); - bool unlock( const void* pwd = nullptr ); - bool is_locked() const; - - bool is_default_value() const; - bool is_preset_value() const; - - cci_originator get_value_origin() const; - - // For brevity only pre-read callbacks are shown - cci_callback_untyped_handle register_pre_read_callback( - const cci_param_pre_read_callback_untyped&, cci_untyped_tag ); - cci_callback_untyped_handle register_pre_read_callback( - const cci_callback_untyped_handle&, cci_typed_tag ); - bool unregister_pre_read_callback( const cci_callback_untyped_handle& ); - - bool unregister_all_callbacks(); - bool has_callbacks() const; - - protected: - // Raw value access provided for derived typed value accessors; no direct access - const void* get_raw_value() const; - const void* get_raw_default_value() const; - void set_raw_value( const void* vp ); - void set_raw_value( const void* vp, const void* pwd ); -}; -``` - -#### 5.6.3.2 Construction - -``` -explicit cci_param_untyped_handle( const cci_originator& originator = cci_originator() ); -``` - -Create an explicitly uninitialized *handle*, i.e. where **`is_valid`** == false. - -``` -cci_param_untyped_handle( cci_param_if& param, const cci_originator& originator ); -``` - -Create a *handle* for the given *parameter*. - -``` -cci_param_untyped_handle( const cci_param_untyped_handle& param_handle ); -``` - -Copy constructor; duplicates the given source *handle*, after which both the original and new *handles* have the same validity and -*originators* but different identities (i.e. if valid then both are registered with the *parameter* and would be separately invalidated if the *parameter* predeceases them). - -``` -cci_param_untyped_handle( cci_param_untyped_handle&& that ); -``` - -Move constructor; duplicate the original *handle*, after which the original *handle* is invalidated. - -#### 5.6.3.3 Destruction - -``` -~cci_param_untyped_handle(); -``` - -Invalidates the *handle* (if valid), thereby unregistering it from the *parameter* as detailed for **`~cci_param_if`** (see [5.4.2.10](#54210-destructor)). - -#### 5.6.3.4 Assignment - -``` -cci_param_untyped_handle& operator=( const cci_param_untyped_handle& param_handle ); -cci_param_untyped_handle& operator=( cci_param_untyped_handle&& that ); -``` - -Assignment to a parameter *handle* consists of: - - - If valid, the existing destination *handle* is first invalidated - meaning that it no longer refers to a parameter. - - - The destination *handle’s parameter* association is set to match - that of the source *handle*, which consequently means they also - have matching validity. - -The *handle’s originator* is not affected by assignment. - -#### 5.6.3.5 Handle validity - -A *handle* constructed against a *parameter* begins its life as a valid *handle* for that *parameter* and remains valid until one of: - - destruction of the *parameter* - - explicit invalidation of the *handle* by **`invalidate`** - - move construction or assignment from the *handle* - -Once invalidated a *handle* remains invalid unless used as the destination for assignment from a valid *handle*. - -``` -bool is_valid() const; -``` - -Returns `true` if the *handle* is valid. - -``` -void invalidate(); -``` - -Invalidates the *handle*: **`is valid`** returns `false` and the object is no longer registered with the *parameter*. - -#### 5.6.3.6 Delegated functions - -With the exception of **`get_originator`**, the remainder of the class delegates predictably to the equivalent **`cci_param_untyped`** functionality with this pattern: - - If the *handle* is invalid then: - - Report a bad *handle* error through **`cci_report_handler`** see ([5.8](#58-error-reporting)). - - If the error report is not thrown as an exception (the SystemC - default behavior but controllable through - `sc_report_handler::set_actions`) then calls **`cci_abort`** - to halt the simulation. - - Calls the matching **`cci_param_untyped`** member function of the - *parameter* instance the *handle* represents, using the *handle*'s - *originator* where an explicit *originator* is catered for: - **`get_cci_value`**, **`set_cci_value`**, *callback* registration - and unregistration. - -The exception to this pattern is **`get_originator`**, which returns the *originator* for the *handle* rather than that of the *parameter*. - -*Example:* - -``` -sc_assert( !(origD == origI) ); -cci_param qp( "q", 1, "q description", CCI_RELATIVE_NAME, origD ); -cci_param_untyped_handle qh = qp.create_param_handle( origI ); -sc_assert( qp.get_originator() == origD ); -sc_assert( qh.get_originator() == origI ); -``` - -### 5.6.4 cci_param_typed_handle - -Typed *handles* extend **`cci_param_untyped_handle`** with type-safe -assignment and *callbacks*. - -``` -template -class cci_param_typed_handle : public cci_param_untyped_handle -{ - public: - /// The parameter's value type. - typedef T value_type; - - // Constructors - explicit cci_param_typed_handle( cci_param_untyped_handle untyped ); - cci_param_typed_handle( const cci_param_typed_handle& ) = default; - cci_param_typed_handle( cci_param_typed_handle&& that ); - - // Assignment - cci_param_typed_handle& operator=( const cci_param_typed_handle& ) = default; - cci_param_typed_handle& operator=( cci_param_typed_handle&& that ) - - // Typed value access - const value_type& operator*() const; const value_type& get_value() const; - - void set_value( const value_type& value ); - void set_value( const value_type& value, const void* pwd ); - const value_type& get_default_value() const; - - // For brevity only pre-read callbacks are shown - cci_callback_untyped_handle register_pre_read_callback( - const cci_param_pre_read_callback_untyped& cb, cci_untyped_tag ); - template - cci_callback_untyped_handle register_pre_read_callback( - cci_param_pre_read_callback_untyped::signature(C::*cb), - C* obj, cci_untyped_tag ); - - typedef typename cci_param_pre_read_callback::type - cci_param_pre_read_callback_typed; - - cci_callback_untyped_handle register_pre_read_callback( - const cci_param_pre_read_callback_typed& cb, - cci_typed_tag = cci_typed_tag() ); - - template - cci_callback_untyped_handle register_pre_read_callback( - typename cci_param_pre_read_callback_typed::signature(C::*cb), - C* obj, cci_typed_tag = cci_typed_tag() ) -}; -``` - -#### 5.6.4.1 Construction - -``` -explicit cci_param_typed_handle( cci_param_untyped_handle untyped ); -``` - -Constructs the *typed handle* from an *untyped handle*, immediately invalidating it if the typeid of the **`value_type`** of the *typed -handle* doesn't match the typeid of the **`value_type`** of the actual **`cci_param_typed`**. - -*Example:* - -``` -cci_param_typed_handle hTest( cci_get_broker().get_param_handle("global.test") ); -if( !hTest.is_valid() ) { /* param missing or wrong type */ } -``` - -``` -cci_param_typed_handle( const cci_param_typed_handle& ); -``` - -Copy constructor; duplicates the given source *handle*, after which both the original and new *handles* have the same validity and -*originators* but different identities (i.e. if valid then both are registered with the *parameter* and would be separately invalidated if the *parameter* predeceases them). - -``` -cci_param_typed_handle( cci_param_typed_handle&& that ); -``` - -Move constructor; duplicate the original *handle*, after which the original *handle* is invalidated. - -#### 5.6.4.2 Assignment - -``` -cci_param_typed_handle& operator=( const cci_param_typed_handle& ); -cci_param_typed_handle& operator=( cci_param_typed_handle&& that ); -``` - -Both copy and move assignment replace the referenced *parameter*, with the same semantics as **`cci_param_untyped_handle`** (see [5.6.3.4](#5634-assignment)). - -#### 5.6.4.3 Typed value access - -The *parameter value may* be read and written directly as the `value_type`. The semantics described for cci_param_typed value access in [5.6.2](#562-cci_param_typed) apply here too. - -``` -const value_type& get_value() const; -const value_type& operator*() const; // convenience form of get_value() -void set_value( const value_type& value ); -void set_value( const value_type& value, const void* pwd ); -const value_type& get_default_value() const; -``` - -#### 5.6.4.4 Callbacks - -Registration functions for *callbacks* providing `value_type` access to the *parameter*. - -**`cci_param_read_event`** objects provide the context for pre-read and post-read *callback* invocations, carrying a *handle* to the -*parameter*, its current value, and the *originator* that the *callback* function was registered with. The class is templated by the -*parameter value* type, with the specialization for void providing the *value* as **`cci_value`**: - -The presence of the *parameter*'s value type in the *callback* signature mirrors the *parameter* hierarchy, with *callbacks* -registered through the **`cci_param_untyped`** class requiring the *untyped* **`cci_param_read_event`**`` and those registered -through **`cci_param_typed`**`` requiring **`cci_param_read_event`**``. When working with a concrete *parameter* object it may prove advantageous to use *untyped callbacks* where the actual *value* is irrelevant or *can* be masked through **`cci_value`** access. For example a generic parameter access logger may have the signature: - -``` -template<> -struct cci_param_read_event -{ - typedef cci_param_read_event type; - typedef cci_value value_type; - const value_type& value; - const cci_originator& originator; - const cci_param_untyped_handle& param_handle; -}; - -template -struct cci_param_read_event -{ - typedef cci_param_read_event type; - typedef T value_type; - const value_type& value; - const cci_originator& originator; - const cci_param_untyped_handle& param_handle; -}; -``` - -The presence of the *parameter*'s value type in the *callback signature* mirrors the *parameter* hierarchy, with callbacks registered through the **`cci_param_untyped`** class requiring the *untyped* **`cci_param_read_event`**`` and those registered through **`cci_param_typed`**`` requiring **`cci_param_read_event`**``. When working with a concrete *parameter* object it may prove advantageous to use *untyped callbacks* where the actual *value* is irrelevant or *can* be masked through **`cci_value`** access. For example a generic parameter access logger may have the signature: - -``` -void log_parameter_read( cci_param_read_event& ev ); -``` - -and so be able to be registered against **`cci_param`**``, **`cci_param`**``, etc. - -### 5.6.5 cci_param_write_event - -Write event objects provide the context for pre-write and post-write *callback* invocations, carrying a *handle* to the *parameter*, its current value, and the *originator* that the *callback* function was registered with. - -The class is templated by the *parameter value* type, with the specialization for void providing the value as **`cci_value`**: - -``` -template<> -struct cci_param_write_event -{ - typedef cci_param_read_event type; - typedef cci_value value_type; - const value_type& old_value; - const value_type& new_value; - const cci_originator& originator; - const cci_param_untyped_handle& param_handle; -}; - -template -struct cci_param_write_event -{ - typedef cci_param_read_event type; - typedef T value_type; - const value_type& old_value; - const value_type& new_value; - const cci_originator& originator; - const cci_param_untyped_handle& param_handle; -}; -``` - -The presence of the *parameter*'s *value* type in the *callback* signature mirrors the *parameter* hierarchy, with *callbacks* -registered through the **`cci_param_untyped`** class requiring the *untyped* **`cci_param_write_event`**`` and those -registered through **`cci_param_typed`**`` requiring **`cci_param_write_event`**``. When working with a concrete -*parameter* object it may prove advantageous to use *untyped callbacks* where the actual *value* is irrelevant or *can* be masked -through **`cci_value`** access. For example a generic pre-write validator for positive numbers might be written: - -``` -bool validate_positive_number( cci_param_read_event& ev ) -{ - return ev.new_value.is_double() && ev.new_value.get_double() >= 0 || - ev.new_value.is_int64() && ev.new_value.get_int64() >= 0 || - ev.new_value.is_uint64(); -} -``` - -and so be able to be registered as a pre_write *callback* against **`cci_param`**``, **`cci_param`**``, etc. - -## 5.7 Brokers - - All *brokers* implement the **`cci_broker_if`** interface. An application *shall* access brokers via a **`cci_broker_handle`**. - - A *broker* aggregates *parameters* defined in the same `sc_object` level and from child objects. For example if a module registers a - *broker* then the module's *parameters* and those belonging to submodules will by default be added to that *broker*. Such *brokers* are referred to as “*local brokers*” since the *parameters* they hold are kept local to that module, rather than being generally enumerable. - - Above the `sc_module` hierarchy is the *global broker*, which aggregates all *parameters* for which no *local broker* is located. - The *global broker shall* be registered before any *parameters* or *local brokers*. - - The *automatic broker* is located by walking up the `sc_object` hierarchy until meeting either a *local broker* registered for - that object or the *global broker*. Only one *broker shall* be registered for each object; similarly a single *global broker* - exists. Attempting to register additional *brokers* reports an error. - - The parent of a *broker* is the next registered *broker* up the `sc_object` hierarchy. Only the *global broker* has no parent. - - Two reference *broker implementations* are provided: **`cci_utils::broker`** which supports selectively delegating *parameters* to a - parent *broker* and **`cci_utils::consuming_broker`** which lacks this delegation ability. A module *may* use such delegation to - expose some public *parameters* beyond its *local broker*. - -### 5.7.1 cci_broker_handle - -A *broker handle* acts as a proxy to a *broker implementation*, delegating the functionality. Note that where the delegated *broker* -function takes an *originator* parameter, it is omitted in the *handle* interface since the *handle* was constructed with the -*originator*. - -Unlike the relationship between *parameters* and *parameter handles*, the relationship between *broker* objects and **`cci_broker_handle`**s is not managed. When a *broker* object is destroyed all *handles* to it are left dangling, without any way for the *handle* users to test their validity. - -``` -class cci_broker_handle -{ - public: - // Constructors - cci_broker_handle( cci_broker_if& broker, const cci_originator& originator ); - cci_broker_handle( const cci_broker_handle& ) = default; - cci_broker_handle( cci_broker_handle&& that ); - - ~cci_broker_handle() = default; - - // Assignment & comparison - cci_broker_handle& operator=( const cci_broker_handle& ); - cci_broker_handle& operator=( cci_broker_handle&& that ); - bool operator==( const cci_broker_if* b ) const; - bool operator!=( const cci_broker_if* b ) const; - - // Originator - cci_originator get_originator() const; - - // Delegated functions - cci_broker_handle create_broker_handle( const cci_originator& originator = cci_originator() ); - - const char* name() const; - void set_preset_cci_value( const std::string& parname, const cci_value& cci_value ); - cci_value get_preset_cci_value( const std::string& parname ) const; - virtual cci_originator get_preset_value_origin( - const std::string& parname ) const = 0; - - std::vector get_unconsumed_preset_values() const; - bool has_preset_value( const std::string& parname ) const; - cci_preset_value_range get_unconsumed_preset_values( - const cci_preset_value_predicate& pred ) const; - void ignore_unconsumed_preset_values( const cci_preset_value_predicate& pred ); - cci_originator get_value_origin( const std::string& parname ) const; - void lock_preset_value( const std::string& parname ); - cci_value get_cci_value( const std::string& parname ) const; - - void add_param( cci_param_if* par ); void remove_param( cci_param_if* par ); - - std::vector get_param_handles() const; - cci_param_range get_param_handles( cci_param_predicate& pred ) const; - cci_param_untyped_handle get_param_handle( const std::string& parname ) const; - - template - cci_param_typed_handle get_param_handle( const std::string& parname ) const; - - cci_param_create_callback_handle register_create_callback( const cci_param_create_callback& cb ); - bool unregister_create_callback( const cci_param_create_callback_handle& cb ); - cci_param_destroy_callback_handle register_destroy_callback( const cci_param_destroy_callback& cb ); - bool unregister_destroy_callback( const cci_param_destroy_callback_handle& cb ); - bool unregister_all_callbacks(); - bool has_callbacks() const; - - bool is_global_broker() const; -}; -``` - -#### 5.7.1.1 Construction - -Construction requires either the pairing of the *broker* interface and the *originator* for the *handle*: - -``` -cci_broker_handle( cci_broker_if& broker, const cci_originator& originator ); -``` - -or an existing *handle* to copy or move these attributes from: - -``` -cci_broker_handle( const cci_broker_handle& ) = default; -cci_broker_handle( cci_broker_handle&& that ); -``` - -#### 5.7.1.2 Assignment - -``` -cci_broker_handle& operator=( const cci_broker_handle& ); -cci_broker_handle& operator=( cci_broker_handle&& that ); -``` - -The destination *handle’s broker* association is set to match that of the source *handle*. The *handle’s originator* is not affected by -assignment. - -#### 5.7.1.3 Comparison - -``` -bool operator==( const cci_broker_if* b ) const; -bool operator!=( const cci_broker_if* b ) const; -``` - -Equality and inequality tests of whether this *broker handle* is for the given *broker implementation*. *Handle originators* are insignificant for this comparison. - -#### 5.7.1.4 Originator - -The *handle* consists of the pairing (**`cci_broker_if`**, **`cci_originator`**), where the *originator* identifies the *handle* to delegated functions such as **`set_preset_cci_value`**. This*originator* is accessible through: - -``` -cci_originator get_originator() const; -``` - -#### 5.7.1.5 Delegated functions - -The remainder of the class delegates predictably to the equivalent **`cci_broker_if`** functionality, supplying the *handle*'s *originator* where a **`cci_originator`** is required. - -### 5.7.2 cci_broker_manager - -The mapping between `sc_object`s and **`cci_broker_if`** *implementations* is maintained by the *broker manager*, which provides an interface for registering new *brokers* and retrieving the responsible *broker* for the current object. The *broker manager* is implemented as a private class, exposing the functionality through global (non-member) functions. - -``` -cci_broker_handle cci_get_broker(); -``` - -Finds the *broker* responsible for the current `sc_object` and returns a *handle* for it, using the `sc_object` also as the *originator* object. If there is no current `sc_object`, for example before the simulation starts and outside the construction of modules, then an -error is reported. Note that the *broker* located may in fact be the *global broker*. - -``` -cci_broker_handle cci_get_global_broker( const cci_originator& originator ); -``` - -Returns a *handle* for the *global broker*. An error is reported if no *global broker* has been registered, or if the function is *called* with a current `sc_object`, for example during module construction or after `sc_start`. - -``` -cci_broker_handle cci_register_broker( cci_broker_if& broker ); -cci_broker_handle cci_register_broker( cci_broker_if* broker ); -``` - -Register the given *broker* as being responsible for the current `sc_object`, including all sub-objects lacking a specific *broker* of their own. In the absence of a current `sc_object` the *broker* is registered as the *global broker*. If a *broker* has already been registered for the `sc_object` then that existing registration is left unchanged and an error is reported. - -Constructing parameters prior to registering a *broker* is permitted in which case they will be registered with the parent’s *broker*. - -### 5.7.3 Reference brokers - -**`cci_utils::broker`** provides the ability to selectively delegate *parameters* to a parent *broker*, by adding their name to a set of *parameter* names to be “exposed”. - -``` -class broker : public consuming_broker -{ - public: - std::set expose; - // ... -}; -``` - -The following example shows a test module using a local **`cci_utils::broker`** to keep one *parameter* private and make another public, the success of which is demonstrated by testing for their existence through the *global broker*. - -*Example:* - -``` -SC_MODULE( testMod ) -{ - private: - cci_utils::broker locBroker; - cci_param* p_private; - cci_param* p_public; - - public: - SC_CTOR( testMod ) : - locBroker( "locBroker" ) - { - cci_register_broker( locBroker ); - locBroker.expose.insert( "testMod.p_public" ); - p_private = new cci_param( "p_private", 1 ); - p_public = new cci_param( "p_public", 2 ); - sc_assert( !locBroker.param_exists("p_glob") ); // can't see into parental broker - sc_assert( locBroker.param_exists("testMod.p_public") ); - sc_assert( locBroker.param_exists("testMod.p_private") ); - } -}; - -int sc_main( int argc, char* argv[] ) -{ - cci::cci_register_broker( new cci_utils::consuming_broker("Global Broker") ); - cci_param p_glob( "p_glob", 3, "Global param", CCI_RELATIVE_NAME, - cci_originator("glob") ); - testMod tm( "testMod" ); - cci_broker_handle gBrok( cci_get_global_broker(cci_originator("glob")) ); - sc_assert( gBrok.param_exists("p_glob") ); - sc_assert( gBrok.param_exists("testMod.p_public") ); - sc_assert( !gBrok.param_exists("testMod.p_private") ); // can only see explicity exposed param -} -``` - -Note that a **`cci_utils::consuming_broker`** was used for the *global broker* since there is no possibility of delegating the *parameter* handling beyond it (although in fact a **`cci_utils::broker`** would function correctly in its place). - -## 5.8 Error reporting - -Where an *application* action is a definitive error, such as attempting to get a *value* as an incorrect type, an error diagnostic is issued through an extension of the customary SystemC `sc_report_handler::report` mechanism with severity `SC_ERROR`. The tacit expectation is that the default `SC_THROW` handling for `SC_ERROR` is in effect. If the environment has been configured to not throw error reports then an *implementation should* remain functional if possible or *call* **`cci_abort`** otherwise. “Functional” means preserving class invariants and not deceiving the application user (e.g. as would be the case when returning the integer zero from an attempted **`get_int`** upon a string value). - -An application that wishes to handle thrown CCI error diagnostics *should* `catch(sc_core::sc_report&)` exceptions (or simply all exceptions) and use **`cci_handle_exception`** to decode the current `sc_report::get_msg_type` as the **`cci_param_failure`** enum. - -``` -enum cci_param_failure -{ - CCI_NOT_FAILURE = 0, // i.e. not a CCI-failure; some other diagnostic - CCI_SET_PARAM_FAILURE, - CCI_GET_PARAM_FAILURE, - CCI_ADD_PARAM_FAILURE, - CCI_REMOVE_PARAM_FAILURE, - CCI_VALUE_FAILURE, - CCI_UNDEFINED_FAILURE, - CCI_ANY_FAILURE = CCI_UNDEFINED_FAILURE -}; -``` - -The **`cci_report_handler`** class provides functions both for emitting CCI-specific `SC_ERROR` diagnostics and decoding a `sc_report` -as a **`cci_param_failure`**. - -``` -class cci_report_handler : public sc_core::sc_report_handler -{ - public: - static void report( sc_core::sc_severity severity, - const char* msg_type, const char* msg, - const char* file, int line ); - - // Functions that throw a report for each cci_param_failure type - static void set_param_failed( const char* msg="", const char* file=nullptr, int line = 0 ); - - static void get_param_failed( const char* msg="", const char* file=nullptr, int line = 0 ); - - static void add_param_failed( const char* msg="", const char* file=nullptr, int line = 0 ); - - static void remove_param_failed( const char* msg="", const char* file=nullptr, int line = 0 ); - - static void cci_value_failure( const char* msg="", const char* file=nullptr, int line = 0 ); - - // Function to return cci_param_failure that matches thrown (or cached) report - static cci_param_failure decode_param_failure( const sc_core::sc_report& rpt ); -}; -``` - -``` -cci_param_failure cci_handle_exception( cci_param_failure expect = CCI_ANY_FAILURE ); -``` - -This function *shall* only be *called* with an exception in flight, i.e. from an exception handler. If the exception is both a CCI error -diagnostic and once decoded as a **`cci_param_failure`** matches the given expected failure type then it is returned, otherwise the exception is re-thrown. Example handling where a pre-write *callback* may reject an update. - -*Example:* - -``` -try { - param = updatedValue; -} catch( … ) { - cci_handle_exception( CCI_SET_PARAM_FAILURE ); - gracefully_handle_update_failure(); -} -``` - -``` -cci_abort(); -``` - -If an *application* determines that for CCI-related reasons (such as unrecoverable misconfiguration) the simulation *shall* be halted -immediately it *should call* **`cci_abort`**, which may emit a suitable diagnostic before terminating via `std::terminate` or `sc_core::sc_sbort` where available. It is usually appropriate to first issue an error report, both to better explain the violation -and to allow the problem to be handled at a higher structural level once the exception has provoked suitable cleanup, e.g. abandoning the -construction of an optional sub-module. - -*Example:* - -``` -if( !param.get_cci_value().try_get(limit_depth) ) { - cci_report_handler::get_param_failed( "Missing FooModule configuration" ); - // Simulation configured with SC_THROW disabled, so object remains alive but unviable - cci_abort(); -} -``` - -Note in this example that **`cci_abort`** is used to ensure a graceful exit when the exception has been suppressed via `sc_report_handler` and the simulation cannot advance successfully. - -## 5.9 Name support functions - -Both *parameters* and *brokers* are required to have unique names relative to each other; this extends to include all named SystemC -objects for SystemC version 2.3.2 and later by using `sc_core::sc_register_hierarchical_name`. In the event of a duplicate, the given name is made unique by suffixing with a sequence number and a warning report is issued (important, since the simulation may now malfunction if the name is relied upon to find or distinguish the entity). Although this avoidance of duplicates is internal to the construction of *parameters* and *brokers* the underlying tools are exposed for application use. - -``` -const char* cci_gen_unique_name( const char* name ); -``` - -Ensures that the given name is unique by testing it against the existing name registry and if necessary suffixing it with a sequence number, of format “_*n*” where *n* is an integer ascending from zero and counting duplicates of that specific name. The return value is a -pointer to an internal string buffer from which the name *shall* be immediately copied. - -This has the explicit effect of registering the name. A name *can* be tested for its registration status, and if registered *may* be unregistered. - -``` -const char* cci_get_name( const char* name ); -``` - -Verify that a name has been registered. If the given name is registered then returns it unmodified, otherwise returns `nullptr`. - -``` -bool cci_unregister_name( const char* name ); -``` - -If the given name is registered then removes it from the registry and returns `true`, otherwise simply returns `false`. The caller *should* be the owner of a name; unregistering names belonging to other entities may result in undefined behavior. - -## 5.10 Version information - -The header file **`cci_configuration`** *shall* include a set of macros, constants, and functions that provide information concerning -the version number of the CCI software distribution. *Applications* may use these macros and constants. - -``` -#define CCI_SHORT_RELEASE_DATE implementation-defined_date // For example, 20180613 - -#define CCI_VERSION_ORIGINATOR implementation-defined_string // “Accellera” - -#define CCI_VERSION_MAJOR implementation-defined_number // 1 - -#define CCI_VERSION_MINOR implementation-defined_number // 0 - -#define CCI_VERSION_PATCH implementation-defined_number // 0 - -#define CCI_IS_PRERELEASE implementation-defined_bool // 0 - -#define CCI_VERSION implementation-defined_string // “1.0.0-Accellera” -``` - -The macros will be defined using the following rules: - 1. Each *implementation-defined_number shall* consist of a sequence of - decimal digits from the character set \[0–9\] not enclosed in - quotation marks. - 2. The originator and pre-release strings *shall* each consist of a - sequence of characters from the character set - \[A–Z\]\[a–z\]\[0–9\]_ enclosed in quotation marks. - 3. The version release date *shall* consist of an ISO 8601 basic format - calendar date of the form YYYYMMDD, where each of the eight - characters is a decimal digit, enclosed in quotation marks. - 4. The **`CCI_IS_PRERELEASE`** flag *shall* be either 0 or 1, not - enclosed in quotation marks. - 5. The **`CCI_VERSION`** string *shall* be set to the value - “major.minor.patch_prerelease-originator” or - “major.minor.patch-originator”, where major, minor, patch, - prerelease, and originator are the values of the corresponding - strings (without enclosing quotation marks), and the presence or - absence of the prerelease string *shall* depend on the value of - the **`CCI_IS_PRERELEASE`** flag. - 6. Each constant *shall* be initialized with the value defined by the - macro of the corresponding name converted to the appropriate data - type. diff --git a/cci/a.md b/cci/a.md deleted file mode 100644 index 5d402896..00000000 --- a/cci/a.md +++ /dev/null @@ -1,193 +0,0 @@ ---- -style: annex ---- - -# Annex A **(informative)** A Introduction to SystemC Configuration - -This clause is informative and is intended to aid the reader in the understanding of the structure and intent of the SystemC Configuration -standard. The SystemC Configuration API is entirely within namespace **`cci`**. Code fragments illustrating this document have an implicit -using namespace **`cci`** for brevity. - -## A.1 Sample code - -### A.1.1 Basic parameter use - -Defining a *parameter* and treating it like a variable: - -``` -cci_param p("param", 17, "Demonstration parameter"); -p = p + 1; -sc_assert( p == 18 ); -``` - -### A.1.2 Parameter handles - -Retrieving a *parameter* by name and safely using the *handle*: - -``` -cci_broker_handle broker(cci_get_broker()); -auto p = new cci_param("p", 17); -string name = p->name(); - -// Getting handle as wrong type fails -cci_param_typed_handle hBad = broker.get_param_handle(name); -sc_assert( !hBad.is_valid() ); - -// Getting handle as right type succeeds -cci_param_typed_handle hGood = broker.get_param_handle(name); -sc_assert( hGood.is_valid() ); - -// Operations upon handle affect original parameter -hGood = 9; -sc_assert(*p == 9); - -// Destroying parameter invalidates handle -delete p; -sc_assert( !hGood.is_valid() ); -``` - -### A.1.3 Enumerating parameters - -Listing all *parameter* names and *values* registered with the *automatic broker*: - -``` -auto broker(cci_get_broker()); -for(auto p : broker.get_param_handles()) { -std::cout << p.name() << "=" << p.get_cci_value() << std::endl; -} -``` - -### A.1.4 Preset and default parameter values - -Setting a *preset value* through the *broker* overrides the *default value* provided as a constructor argument: - -``` -auto broker(cci_get_broker()); -broker.set_preset_cci_value("module.sip", cci::cci_value(7)); -auto sip = cci_param("sip", 42); -sc_assert( sip == 7 ); -sc_assert( sip.is_preset_value() && !sip.is_default_value() ); -``` - -### A.1.5 Linking parameters with callbacks - -Uses a *callback* function to set *parameter* “triple” to three times the value of some other modified *parameter*: - -``` -void set_triple_callback(const cci_param_write_event& ev) { - auto broker(cci_get_broker()); - cci_param_typed_handle h = broker.get_param_handle("m.triple"); - h = 3 * cci_param_typed_handle(ev.param_handle); -} - -void test() { - cci_param p("p", 0); - cci_param triple("triple", 0); - p.register_post_write_callback(set_triple_callback); - p = 7; - sc_assert(triple == 21); -} -``` - -## A.2 Interface classes - -The interface classes are described in detail in the main document body; what follows here is a description of the relationships of some -major classes, providing a conceptual model for locating functionality. - -### A.2.1 cci_value - -Variant data types are provided by the **`cci_value`** hierarchy (depicted in [Figure A.1](#figure-a1)). The encapsulated type *may* be: - - one of the directly supported standard data types: `bool`, `int`, - `unsigned int`, `sc_dt::int64`, `sc_dt::uint64`, `double`, or - `std::string`. - - a user-defined type such as a `struct`, where an application provides - the definition for the converter **`cci_value_converter`**`< `*`type`*` >` - - a list of **`cci_value`** objects (**`cci_value_list`**). - - a string-keyed map of **`cci_value`** objects (**`cci_value_map`**). - -Accessors such as **`get_int64`** retrieve the value, verifying that the type matches or trivially coerces to the accessor type. For -example: - -``` -cci_value vi(-7); -auto i32 = vi.get_int(); // succeeds -auto i64 = vi.get_int64(); // succeeds -auto d = vi.get_double(); // succeeds -auto u64 = vi.get_uint64(); // reports CCI_VALUE_FAILURE error -``` - -Standard and user-defined types are set by initialization (initially through the constructor, subsequently through a setter function). -**`set_list`** and **`set_map`** return adapter objects (**`cci_value::list_reference`** and **`cci_value::map_reference`** respectively) providing appropriate container methods: - -``` -cci_value val; -cci_value::map_reference vm(val.set_map()); -vm.push_entry("width", 7.3); -vm.push_entry("label", “Stride”); -optionClass defaultOptions; -vm.push_entry("options", defaultOptions); -``` - -Containers can be nested: - -``` -cci_value_map options; -cci_value_list enabledBits; -enabledBits.push_back(0).push_back(3); // b01001 -options.push_entry(“widget0_flags”, enabledBits); -enabledBits.pop_back(); // b00001 -enabledBits.push_back(4); // b10001 -options.push_entry(“widget1_flags”, enabledBits); -``` - -To make the interfaces more granular each of the **`cci_value`** sub-hierarchies has `_cref` classes with accessor methods and `_ref` -classes with modifier methods. - -{% include figure - reference="Figure A.1" - caption="cci_value hierarchy" - alt-text="" - class="fixed" - images="figure2.png" -%} - -### A.2.2 cci_param - -*Parameter* functionality is implemented by the small hierarchy shown in [Figure A.2](#figure-a2) The final class,**`cci_param_typed`**, is parameterized by both data type `T` and mutability TM (with mutability defaulted to mutable) and is instantiated with both a name and a *default value* to create the `*parameter* and add it to a *broker*: - - The final *parameter* name may include the hosting object name and a suffix to make it unique. - - If no *broker* is specified then the *broker* associated with the current context is used. - - A description and *originator* may optionally be given. - -{% include figure - reference="Figure A.2" - caption="cci_param hierarchy" - alt-text="" - class="fixed" - images="figure3.png" - image-height="15" -%} - -The base class **`cci_param_untyped`** and the interface class **`cci_param_if`** provide most of the functionality free of concrete type and so are suitable for library interfaces. - -For brevity **`cci_param`**`` is an alias for **`cci_param_typed`**``, as seen in the above code samples. - -### A.2.3 cci_param_handle - -*Parameter handles* provide a safe reference to *parameters*: safety is ensured by asserting the validity of the *handle* upon all operations and invalidating *handles* when their *parameter* is destroyed. Using an invalid *handle* results in an `SC_ERROR` report. As with *parameters* both *untyped* and *typed handles* exist: *untyped handles* are returned from *parameter* lookups and *callbacks* and *typed handles* provide direct access to the *typed parameter value* and are safely constructible from the *untyped handle*: - -**`cci_param_typed_handle`**`` `val(broker.`**`get_param_handle`**`("mode")); if(val != DEFAULT_MODE) { ... }` - -{% include figure - reference="Figure A.3" - caption="cci_param_handle hierarchy" - alt-text="" - class="fixed" - images="figure4.png" - image-height="10" -%} - -For convenience **`cci_param_handle`** is an aliased for **`cci_param_untyped handle`**. - -## A.3 Error reporting - -Errors are reported through the sc_report_handler::report mechanism with severity SC_ERROR and the message type prefixed with `__CCI_SC_REPORT_MSG_TYPE_PREFIX__` (currently "/Accellera/CCI/"). A convenience function **`cci_report_handler::get_param_failure`** decodes common CCI error messages as the **`cci_param_failure`** enum. diff --git a/cci/b.md b/cci/b.md deleted file mode 100644 index fef76fd2..00000000 --- a/cci/b.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -style: annex ---- - -# Annex B **(informative)** Glossary - -This glossary contains brief, informal descriptions for a number of terms and phrases used in this standard. Where appropriate, the complete, formal definition of each term or phrase is given in themain body of the standard. Each glossary entry contains either the clause number of the definition in the main body of the standard. - -**automatic broker**: The *broker* that has responsibility for the current module hierarchy, obtained by calling **`cci_get_broker`**. This will be the *broker* registered at, or most closely above, the current module hierarchy and will be the *global broker* in the event that no *local brokers* have been registered. *Parameters* are registered with the *automatic broker* at the time of their creation, unless explicitly overridden. The *automatic broker* is sometimes referred to as the “responsible” broker. (See [5.6.2.2](05.html#5622-construction)) - -**broker**: An object that aggregates *parameters*, providing container behaviors such as finding and enumerating, as well as managing preset values for *parameters*. A *global broker* is requisite; additional *local brokers* may be instantiated, e.g. to confine *parameters* to a sub-assembly. (See [5.7](05.html#57-brokers)) - -**broker handle**: An object that acts as a proxy to a *broker implementation* while relaying an *originator* representing the *handle* owner. (See [5.7.1](05.html#571-cci_broker_handle)) - -**broker manager**: A private singleton class accessed via global functions to register brokers, using **`cci_register_broker`**, and retrieve the currently responsible broker, using **`cci_get_broker`**. (See [5.7.2](05.html#572-cci_broker_manager)) - -**callback**: A function registered to be invoked when a particular action happens. Both *brokers* and *parameters* support *callbacks* to -enable custom processing of actions of interest, such as the creation of a new *parameter* or accessing a *parameter value*. (See [5.4.3.6](05.html#5436-broker-callbacks) for *broker callbacks* and [5.4.2.8](05.html#5428-callbacks) for *parameter callbacks*) - -**callback handle**: An object that is returned from successfully registering a *callback* function; it is used as an identifier to -subsequently unregister that *callback* function. (See [5.4.2.8](05.html#5428-callbacks)) - -**global broker**: This *broker* must be registered before any *parameters* are constructed and it has responsibility (1) outside of the module hierarchy and (2) for all module hierarchies that have no registered *local broker*. A *global broker handle* is obtained outside the module hierarchy by calling **`cci_get_global_broker`** within the module hierarchy, it is returned by **`cci_get_broker`** when appropriate. (See [5.7](05.html#57-brokers)) - -**local broker**: A *broker* explicitly registered at a specific level in the module hierarchy, becoming the *automatic broker* for that module and submodules below it that don’t register a *local broker* themselves. (See [5.7](05.html#57-brokers)) - -**originator**: An object used to identify the source of *parameter value* and *preset value* changes. Originators are embedded within *handles* allowing source identification to be provided in a largely implicit manner. (See [5.4.1](05.html#541-cci_originator)) - -**parameter**: An object representing a named configuration *value* of a specific compile-time type. *Parameters* are typically created -within modules from which their name is derived, managed by brokers, and accessed externally via *parameter handles*. (See [5.6](05.html#56-parameters)) - -**(parameter) default value**: The *value* provided as an argument to the *parameter*’s constructor. This *value* is supplanted by the -preset value, when present. (See [5.4.2.3](05.html#5423-value-origin)) - -**parameter handle**: An object that acts as a proxy to a *parameter* while relaying an *originator* representing the *handle* -owner. *Parameter handles* can be either *untyped* (See [5.6.3](05.html#563-cci_param_untyped_handle)) or *typed* (See [5.6.4](05.html#564-cci_param_typed_handle)). - -**parameter value**: The current *value* of the *parameter*, accessible in either an *untyped* or *typed* manner. (See [5.4.2.1](05.html#5421-value-and-data-type)) - -**(parameter) value origin**: The *originator* that most recently set the *parameter*’s value. (See [5.4.2.3](05.html#5423-value-origin)) - -**(parameter) preset value**: A *value* used to initialize the *parameter*, overriding its default value. Preset values are supplied to the appropriate *broker* prior to constructing or resetting the *parameter*. (See [5.4.3.4](05.html#5434-parameter-initialization)). - -**(parameter) underlying data type**: The specific compile-time type supplied as a template instantiation argument in the *parameter*’s declaration. Syntactically, this is referenced as the *parameter*’s **`value_type`**. (See [5.6.2.1](05.html#5621-value_type)) - -**typed (parameter access)**: Using interfaces based on the *parameter*’s *underlying data type* to access a *parameter value*. (See [5.6.2](05.html#562-cci_param_typed)) - -**untyped (parameter access)**: Using interfaces based on **`cci_value`** to access a *parameter value*. (See [5.6.1](05.html#561-cci_param_untyped)) diff --git a/cci/c.md b/cci/c.md deleted file mode 100644 index 53f7688b..00000000 --- a/cci/c.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -style: annex ---- - -# Annex C **(informative)** SystemC Configuration modeler guidelines - -The following guidelines are provided to help ensure proper and most -effective use of this standard. - -## C.1 Declare parameter instances as protected or private members - -Making *parameters* non-`public` ensures they are accessed via a *handle* provided by a broker, adhering to any *broker* access policies and properly tracking *originator* information. - -## C.2 Initialize broker handles during module elaboration - -*Broker handles should* be obtained, and stored for later use, during elaboration when the well-defined current module can be used to -accurately determine implicit *originator* information. - -## C.3 Prefer typed parameter value access over untyped, when possible, for speed - -When a *parameter*’s *underlying data type* is known, access via the *typed handle* is preferred over the *untyped handle* since it avoids the overhead associated with **`cci_value`** conversions. - -## C.4 Provide parameter descriptions - -Providing a description of *parameters*, which can only be done during *parameter* construction, is recommended when the *parameter*’s purpose and meaning are not entirely clear from the name. Tools can relay descriptions to users to give insights about *parameters*. diff --git a/cci/d.md b/cci/d.md deleted file mode 100644 index bde53218..00000000 --- a/cci/d.md +++ /dev/null @@ -1,78 +0,0 @@ ---- -style: annex ---- - -# Annex D **(informative)** Enabling user-defined parameter value types - -To be able to instantiate a **`cci_param_typed`** with some user-defined type `VT`, that type must provide these features: - - default constructor: `VT()` (DefaultConstructible in C++ concept terminology). - - copy constructor: `VT(const VT&`) (CopyConstructible). - - value type assignment operator: `operator=(const VT&)` (CopyAssignable) - - value type equality operator: `operator==(const VT&)` (EqualityComparable) - - **`cci_value_converter`**`` defined. - -The following example takes a small class `custom_type`, the pairing of an integer and string, and enables use such as: - -``` -custom_type ct1( 3, "foo" ); -cci_param pct( "p1", ct1 ); -custom_type ct2 = pct; -``` - -Emphasized in italics below is the added support code. - -``` -class custom_type -{ - private: - int val_; - string name_; - friend class cci_value_converter< custom_type >; - - public: - custom_type() - : val_(0) {} - custom_type( int val, const char* name ) - : val_(val), name_(name) {} - bool operator==( const custom_type& rhs ) const - { - return val_ == rhs.val_ && name_ == rhs.name_; - } -}; - -template<> -struct cci_value_converter< custom_type > -{ - typedef custom_type type; - static bool pack( cci_value::reference dst, type const& src ) - { - dst.set_map() - .push_entry( "val", src.val_ ) - .push_entry( "name", src.name_ ); - return true; - } - - static bool unpack( type& dst, cci_value::const_reference src ) - { - // Highly defensive unpacker; probably could check less - assert( src.is_map() ); - cci_value::const_map_reference m = src.get_map(); - return m.has_entry( "val" ) - && m.has_entry( "name" ) - && m.at( "val" ).try_get( dst.val_ ) - && m.at( "name" ).try_get( dst.name_ ); - } -}; -``` - -There is no explicit stability requirement for the packing and unpacking operations; for example it is not required that: - -``` -T x; -cci_value vX( x ); -T y = vX.get(); -sc_assert( x == y ); -``` - -and for some data types such as floating point it may not be practicable, nor desirable to encourage thinking of equality as a -useful concept when comparing types. However in general such behavior may astonish users, so stability may be a sensible default goal. diff --git a/cci/images/screen-pdf/accellera_logo.svg b/cci/images/screen-pdf/accellera_logo.svg deleted file mode 100644 index 0f38a044..00000000 --- a/cci/images/screen-pdf/accellera_logo.svg +++ /dev/null @@ -1,2366 +0,0 @@ - - - - - - - - - - image/svg+xml - - - - - - - - - diff --git a/cci/images/screen-pdf/figure1.png b/cci/images/screen-pdf/figure1.png deleted file mode 100755 index 42be3f71..00000000 Binary files a/cci/images/screen-pdf/figure1.png and /dev/null differ diff --git a/cci/images/screen-pdf/figure1.svg b/cci/images/screen-pdf/figure1.svg deleted file mode 100755 index 5294fa2f..00000000 --- a/cci/images/screen-pdf/figure1.svg +++ /dev/null @@ -1,1067 +0,0 @@ - - - - - - image/svg+xml - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - cci_broker_if - - cci_param(_untyped)_handle - - cci_param - - parameter owner - (SystemC - module) - - p - arameter user - (SystemC module, tool, etc.) - - - typed access - untyped - access - request - parameter - handle - - - specify - preset - value - (overrides default) - - cci_param_typed_handle - - - r - egistration, i - nitialization - - specify - default value - - a - - b - - d - - c - - diff --git a/cci/images/screen-pdf/figure2.png b/cci/images/screen-pdf/figure2.png deleted file mode 100755 index f0bece41..00000000 Binary files a/cci/images/screen-pdf/figure2.png and /dev/null differ diff --git a/cci/images/screen-pdf/figure3.png b/cci/images/screen-pdf/figure3.png deleted file mode 100755 index 5681c174..00000000 Binary files a/cci/images/screen-pdf/figure3.png and /dev/null differ diff --git a/cci/images/screen-pdf/figure4.png b/cci/images/screen-pdf/figure4.png deleted file mode 100755 index caa8dcc9..00000000 Binary files a/cci/images/screen-pdf/figure4.png and /dev/null differ diff --git a/cci/index.md b/cci/index.md deleted file mode 100644 index f0ab1fe5..00000000 --- a/cci/index.md +++ /dev/null @@ -1,426 +0,0 @@ ---- -style: index ---- - - -Index -===== - -A -- - -add_metadata, 16 - -add_param, 26 - -add_param_failed, 51 - -add_param_handle, 20 - -application, 4 - -B -- - -broker, 49 - -C -- - -**callbacks broker**, 25 - -**parameter**, 17 - -category, 29 - -CCI_ABSOLUTE_NAME, 11 - -CCI_ADD_PARAM_FAILURE, 50 - -CCI_ANY_FAILURE, 50 - -CCI_BOOL_PARAM, 11 - -CCI_BOOL_VALUE, 26 - -**cci_broker_handle**, 47 - -**cci_broker_if**, 20 - -**cci_broker_manager**, 49 - -cci_configuration, 10 - -cci_gen_unique_name, 51 - -cci_get_name, 52 - -CCI_GET_PARAM_FAILURE, 50 - -cci_handle_exception, 51 - -CCI_IMMUTABLE_PARAM, 10 - -CCI_INTEGRAL_PARAM, 11 - -CCI_INTEGRAL_VALUE, 26 - -CCI_LIST_PARAM, 11 - -CCI_LIST_VALUE, 26 - -CCI_MUTABLE_PARAM, 10 - -**cci_name_type**, 11 - -CCI_NOT_FAILURE, 50 - -CCI_NULL_VALUE, 26 - -**cci_originator**, 11 - -CCI_OTHER_MUTABILITY, 10 - -CCI_OTHER_PARAM, 11 - -CCI_OTHER_VALUE, 26 - -cci_param, 37 - -cci_param_callback_if, 13 - -**cci_param_data_category**, 11 - -cci_param_failure, 50 - -**cci_param_if**, 13 - -**cci_param_mutable_type**, 10 - -**cci_param_typed**, 37 - -**cci_param_typed_handle**, 44 - -**cci_param_untyped**, 36 - -**cci_param_untyped_handle**, 41 - -**cci_param_write_event**, 46 - -CCI_REAL_PARAM, 11 - -CCI_REAL_VALUE, 26 - -CCI_RELATIVE_NAME, 11 - -CCI_REMOVE_PARAM_FAILURE, 50 - -cci_report_handler, 50 - -CCI_SET_PARAM_FAILURE, 50 - -CCI_STRING_PARAM, 11 - -CCI_STRING_VALUE, 26 - -CCI_UNDEFINED_FAILURE, 50 - -cci_unregister_name, 52 - -**cci_value**, 26 - -**cci_value_category**, 26 - -cci_value_failure, 51 - -CCI_VALUE_FAILURE, 50 - -**cci_value_list**, 32 - -**cci_value_map**, 34 - -consuming_broker, 49 - -create_broker_handle, 24 - -create_param_handle, 20 - -D -- - -decode_param_failure, 51 - -E -- - -empty - -cci_value_list, 33 - -equals, 17 - -F -- - -from_json, 32 - -G -- - -get, 31 - -get_bool, 30 - -get_cci_value, 14 - -cci_broker_if, 22 - -get_data_category, 14 - -get_default_cci_value, 14 - -get_default_value, 40 - -get_description, 16 - -get_double, 30 - -get_int, 30 - -get_int64, 30 - -get_list, 31 - -get_map, 31 - -get_metadata, 16 - -get_mutable_type, 17 - -get_number, 30 - -get_object, 12 - -get_originator cci_param_if, 15 - -cci_param_untyped_handle, 44 - -get_param_failed, 51 - -get_param_handle, 22 - -get_param_handles, 22 - -get_preset_cci_value, 23 - -get_preset_value_origin, 23 - -get_raw_default_value, 15 - -get_raw_value, 15, 40 - -get_string, 31 - -get_type_info, 14 - -get_uint, 30 - -get_uint64, 30 - -get_unconsumed_preset_values, 24 - -get_value, 39 - -get_value_origin, 15 - -cci_broker_if, 22 - -global broker, 47 global variables - -parameters (prohibited), 39 - -H -- - -has_callbacks cci_broker_if, 25 - -cci_param_if, 20 - -has_preset_value, 23 - -I -- - -ignore_unconsumed_preset_values, 24 - -implementation, 4 - -invalidate, 43 - -is_bool, 29 - -is_default_value, 15 - -is_double, 29 - -is_global_broker, 22 - -is_int, 29 - -is_int64, 29 - -is_list, 30 - -is_locked, 17 - -is_map, 30 - -is_null, 29 - -is_number, 29 - -is_preset_value, 15 - -is_same, 32 - -is_string, 29 - -is_uint, 29 - -is_uint64, 29 - -is_unknown, 12 - -is_valid - -cci_param_untyped_handle, 43 - -L -- - -local brokers, 47 - -lock, 17 - -lock_preset_value, 23 - -M -- - -move, 29 - -N -- - -name - -cci_broker_if, 22 - -cci_orginator, 12 - -cci_param_if, 16 - -O -- - -operator< cci_originator, 13 - -operator= cci_originator, 12 - -cci_param_typed, 40 - -cci_param_typed_handle, 45 - -cci_param_untyped_handle, 43 - -operator== cci_originator, 13 - -R -- - -register_create_callback, 25 - -register_destroy_callback, 25 - -register_post_read_callback, 18 - -register_post_write_callback, 18 - -register_pre_read_callback, 18, 41 - -register_pre_write_callback, 18 - -remove_param, 26 - -remove_param_failed, 51 - -remove_param_handle, 20 - -reset, 14 - -S -- - -set, 32 - -set_bool, 32 - -set_cci_value, 14 - -set_description, 16 - -set_double, 32 - -set_int, 32 - -set_int64, 32 - -set_list, 32 - -set_map, 32 - -set_null, 32 - -set_param_failed, 51 - -set_preset_cci_value, 23 - -set_raw_value, 15, 40 - -set_string, 32 - -set_uint, 32 - -set_uint64, 32 - -set_value, 40 - -swap, 29 - -cci_originator, 12 - -T -- - -to_json, 32 - -try_get, 31 - -try_set, 32 - -U -- - -unlock, 17 - -unregister_all_callbacks cci_broker_if, 25 - -cci_param_if, 20 - -unregister_create_callback, 25 - -unregister_destroy_callback, 25 - -unregister_pre_read_callback, 19 - -unregister_pre_write_callback, 19 diff --git a/cci/styles/app.scss b/cci/styles/app.scss deleted file mode 100644 index fb025074..00000000 --- a/cci/styles/app.scss +++ /dev/null @@ -1,53 +0,0 @@ ---- -# App styles ---- - -// What is this? -// ------------- -// This file assembles the design and typography for this book. -// It inherits the variables set in the project's _sass folder. -// You can override those variables by using them here, -// without the `!default` that sets the default value in _sass. -// -// How to use it -// ------------- -// For book-specific styles (i.e. not project defaults): -// 1. Copy variables you want to override from _sass/app.scss, -// and remove `!default` to override the project default. -// 2. Add book-specific font imports below. -// 3. Add your own custom CSS or Sass at the bottom. - - -// ------------- -// Set variables -// ------------- - -// Edition suffix: identifies this edition in certain classes (e.g. in _epub-fitting.scss). -$edition-suffix: null; - - -// ------------ -// Import fonts -// ------------ - -// Add @font-face rules for fonts you specify here. -// Add the actual font files to `../fonts` or `../../assets/fonts`. -// Use #{$path-to-root-directory} to allow overriding per translation. E.g.: -// `src: url(#{$path-to-root-directory}/assets/fonts/CrimsonPro-Regular.ttf);` -// For snippets, try https://github.com/arthurattwell/font-faces - - -// ------------- -// Master theme -// ------------- - -// Import default project styles -@import 'template/app'; - - -// ------------- -// Custom styles -// ------------- - -// Add any custom Sass or CSS here. - diff --git a/cci/styles/epub.scss b/cci/styles/epub.scss deleted file mode 100644 index 630498b0..00000000 --- a/cci/styles/epub.scss +++ /dev/null @@ -1,52 +0,0 @@ ---- -# EPUB styles ---- - -// What is this? -// ------------- -// This file assembles the design and typography for this book. -// It inherits the variables set in the project's _sass folder. -// You can override those variables by using them here, -// without the `!default` that sets the default value in _sass. -// -// How to use it -// ------------- -// For book-specific styles (i.e. not project defaults): -// 1. Copy variables you want to override from _sass/epub.scss, -// and remove `!default` to override the project default. -// 2. Add book-specific font imports below. -// 3. Add your own custom CSS or Sass at the bottom. - - -// ------------- -// Set variables -// ------------- - -// Edition suffix: identifies this edition in certain classes (e.g. in _epub-fitting.scss). -$edition-suffix: null; - - -// ------------ -// Import fonts -// ------------ - -// If you're embedding epub fonts, add @font-face rules -// for fonts you specify here. -// Add the actual font files to `_epub/fonts`. -// For snippets, try https://github.com/arthurattwell/font-faces - - -// ------------- -// Master theme -// ------------- - -// Import master styles -@import 'template/epub'; - - -// ------------- -// Custom styles -// ------------- - -// Add any custom Sass or CSS here. - diff --git a/cci/styles/hyphenation.dic b/cci/styles/hyphenation.dic deleted file mode 100644 index a423e6fa..00000000 --- a/cci/styles/hyphenation.dic +++ /dev/null @@ -1,8 +0,0 @@ ---- -# This YAML frontmatter makes Jekyll process this file. -# So you can use Liquid tags to include files such as -# other hyphenation dictionaries, e.g. -# `{% include_relative hyph-en-gb.pat %}` -# or to use hyphenation in certain cases, e.g. variants. ---- - diff --git a/cci/styles/print-pdf.scss b/cci/styles/print-pdf.scss deleted file mode 100644 index d41f0a95..00000000 --- a/cci/styles/print-pdf.scss +++ /dev/null @@ -1,58 +0,0 @@ ---- -# Print styles ---- - -// What is this? -// ------------- -// This file assembles the design and typography for this book. -// It inherits the variables set in the project's _sass folder. -// You can override those variables by using them here, -// without the `!default` that sets the default value in _sass. -// -// How to use it -// ------------- -// For book-specific styles (i.e. not project defaults): -// 1. Copy variables you want to override from _sass/print-pdf.scss, -// and remove `!default` to override the project default. -// 2. Add book-specific font imports below. -// 3. Add your own custom CSS or Sass at the bottom. - - -// ------------- -// Set variables -// ------------- - -// Edition suffix: identifies this edition in page-fitting classes (in _print-fitting.scss). -// For instance, a .tighten class in HTML might apply to your bookshop edition, but not the schools edition. -// A suffix '-schools-edn' would mean only tags with that suffix would apply to that edition, e.g. {:.tighten-schools-edn} -// If you're only planning one edition and use default tags ({:.tighten} not {:.tighten-schools-edn}), leave as null. -$edition-suffix: null; - - -// ------------ -// Import fonts -// ------------ - -// Add @font-face rules for fonts you specify here. -// Add the actual font files to `../fonts` or `../../assets/fonts`. -// Use #{$path-to-root-directory} to allow overriding per translation. E.g.: -// `src: url(#{$path-to-root-directory}/assets/fonts/CrimsonPro-Regular.ttf);` -// For snippets, try https://github.com/arthurattwell/font-faces -// By default, a print-font-faces partial will include rules -// for Crimson Pro, Source Sans Pro, and Ubuntu Mono. - - -// ------------- -// Master theme -// ------------- - -// Import master styles -@import 'template/print-pdf'; - - -// ------------- -// Custom styles -// ------------- - -// Add any custom Sass or CSS here. - diff --git a/cci/styles/screen-pdf.scss b/cci/styles/screen-pdf.scss deleted file mode 100644 index 2b4b1536..00000000 --- a/cci/styles/screen-pdf.scss +++ /dev/null @@ -1,58 +0,0 @@ ---- -# Screen PDF styles ---- - -// What is this? -// ------------- -// This file assembles the design and typography for this book. -// It inherits the variables set in the project's _sass folder. -// You can override those variables by using them here, -// without the `!default` that sets the default value in _sass. -// -// How to use it -// ------------- -// For book-specific styles (i.e. not project defaults): -// 1. Copy variables you want to override from _sass/screen-pdf.scss, -// and remove `!default` to override the project default. -// 2. Add book-specific font imports below. -// 3. Add your own custom CSS or Sass at the bottom. - - -// ------------- -// Set variables -// ------------- - -// Edition suffix: identifies this edition in page-fitting classes (in _print-fitting.scss). -// For instance, a .tighten class in HTML might apply to your bookshop edition, but not the schools edition. -// A suffix '-schools-edn' would mean only tags with that suffix would apply to that edition, e.g. {:.tighten-schools-edn} -// If you're only planning one edition and use default tags ({:.tighten} not {:.tighten-schools-edn}), leave as null. -$edition-suffix: null; - - -// ------------ -// Import fonts -// ------------ - -// Add @font-face rules for fonts you specify here. -// Add the actual font files to `../fonts` or `../../assets/fonts`. -// Use #{$path-to-root-directory} to allow overriding per translation. E.g.: -// `src: url(#{$path-to-root-directory}/assets/fonts/CrimsonPro-Regular.ttf);` -// For snippets, try https://github.com/arthurattwell/font-faces -// By default, a print-font-faces partial will include rules -// for Crimson Pro, Source Sans Pro, and Ubuntu Mono. - - -// ------------- -// Master theme -// ------------- - -// Import master styles -@import 'template/screen-pdf'; - - -// ------------- -// Custom styles -// ------------- - -// Add any custom Sass or CSS here. - diff --git a/cci/styles/web.scss b/cci/styles/web.scss deleted file mode 100644 index 8ad54f00..00000000 --- a/cci/styles/web.scss +++ /dev/null @@ -1,51 +0,0 @@ ---- -# Web styles ---- - -// What is this? -// ------------- -// This file assembles the design and typography for this book. -// It inherits the variables set in the project's _sass folder. -// You can override those variables by using them here, -// without the `!default` that sets the default value in _sass. -// -// How to use it -// ------------- -// For book-specific styles (i.e. not project defaults): -// 1. Copy variables you want to override from _sass/web.scss, -// and remove `!default` to override the project default. -// 2. Add book-specific font imports below. -// 3. Add your own custom CSS or Sass at the bottom. - - -// ------------- -// Set variables -// ------------- - -// Edition suffix: identifies this edition in certain classes (e.g. in _epub-fitting.scss). -$edition-suffix: null; - - -// ------------ -// Import fonts -// ------------ - -// Add @font-face rules for fonts you specify here. -// Add the actual font files to `../fonts` -// For snippets, try https://github.com/arthurattwell/font-faces - - -// ------------- -// Master theme -// ------------- - -// Import master styles -@import 'template/web'; - - -// ------------- -// Custom styles -// ------------- - -// Add any custom Sass or CSS here. - diff --git a/ieee-sa-standard-template/0-0-titlepage.md b/ieee-sa-standard-template/0-0-titlepage.md deleted file mode 100644 index 356bf9e8..00000000 --- a/ieee-sa-standard-template/0-0-titlepage.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -style: title-page ---- - -{% include title-page-ieee %} diff --git a/ieee-sa-standard-template/0-1-abstract.md b/ieee-sa-standard-template/0-1-abstract.md deleted file mode 100644 index 9690c74f..00000000 --- a/ieee-sa-standard-template/0-1-abstract.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -style: frontmatter ---- - -{% include abstract-page-ieee %} diff --git a/ieee-sa-standard-template/0-2-notice.md b/ieee-sa-standard-template/0-2-notice.md deleted file mode 100644 index 1d949af4..00000000 --- a/ieee-sa-standard-template/0-2-notice.md +++ /dev/null @@ -1,88 +0,0 @@ ---- -style: frontmatter ---- - -# Important Notices and Disclaimers Concerning IEEE Standards Documents - -IEEE Standards documents are made available for use subject to important notices and legal disclaimers. These notices and disclaimers, or a reference to this page (), appear in all standards and may be found under the heading “Important Notices and Disclaimers Concerning IEEE Standards Documents.” - -# Notice and Disclaimer of Liability Concerning the Use of IEEE Standards Documents -{:.no-bookmark} - -IEEE Standards documents are developed within IEEE Societies and subcommittees of IEEE Standards Association (IEEE SA) Board of Governors. IEEE develops its standards through an accredited consensus development process, which brings together volunteers representing varied viewpoints and interests to achieve the final product. IEEE Standards are documents developed by volunteers with scientific, academic, and industry-based expertise in technical working groups. Volunteers are not necessarily members of IEEE or IEEE SA and participate without compensation from IEEE. While IEEE administers the process and establishes rules to promote fairness in the consensus development process, IEEE does not independently evaluate, test, or verify the accuracy of any of the information or the soundness of any judgments contained in its standards. - -IEEE makes no warranties or representations concerning its standards, and expressly disclaims all warranties, express or implied, concerning this standard, including but not limited to the warranties of merchantability, fitness for a particular purpose and non-infringement. In addition, IEEE does not warrant or represent that the use of the material contained in its standards is free from patent infringement. IEEE standards documents are supplied “AS IS” and “WITH ALL FAULTS.” - -Use of an IEEE standard is wholly voluntary. The existence of an IEEE Standard does not imply that there are no other ways to produce, test, measure, purchase, market, or provide other goods and services related to the scope of the IEEE standard. Furthermore, the viewpoint expressed at the time a standard is approved and issued is subject to change brought about through developments in the state of the art and comments received from users of the standard. - -In publishing and making its standards available, IEEE is not suggesting or rendering professional or other services for, or on behalf of, any person or entity, nor is IEEE undertaking to perform any duty owed by any other person or entity to another. Any person utilizing any IEEE Standards document, should rely upon his or her own independent judgment in the exercise of reasonable care in any given circumstances or, as appropriate, seek the advice of a competent professional in determining the appropriateness of a given IEEE standard. - -IN NO EVENT SHALL IEEE BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO: THE NEED TO PROCURE SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE PUBLICATION, USE OF, OR RELIANCE UPON ANY STANDARD, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE AND REGARDLESS OF WHETHER SUCH DAMAGE WAS FORESEEABLE. - -# Translations -{:.no-bookmark} - -The IEEE consensus development process involves the review of documents in English only. In the event that an IEEE standard is translated, only the English version published by IEEE is the approved IEEE standard. - -# Official statements -{:.no-bookmark} - -A statement, written or oral, that is not processed in accordance with the IEEE SA Standards Board Operations Manual shall not be considered or inferred to be the official position of IEEE or any of its committees and shall not be considered to be, nor be relied upon as, a formal position of IEEE. At lectures, symposia, seminars, or educational courses, an individual presenting information on IEEE standards shall make it clear that the presenter’s views should be considered the personal views of that individual rather than the formal position of IEEE, IEEE SA, the Standards Committee, or the Working Group. Statements made by volunteers may not represent the formal position of their employer(s) or affiliation(s). - -# Comments on standards -{:.no-bookmark} - -Comments for revision of IEEE Standards documents are welcome from any interested party, regardless of membership affiliation with IEEE or IEEE SA. However, **IEEE does not provide interpretations, consulting information, or advice pertaining to IEEE Standards documents**. - -Suggestions for changes in documents should be in the form of a proposed change of text, together with appropriate supporting comments. Since IEEE standards represent a consensus of concerned interests, it is important that any responses to comments and questions also receive the concurrence of a balance of interests. For this reason, IEEE and the members of its Societies and subcommittees of the IEEE SA Board of Governors are not able to provide an instant response to comments, or questions except in those cases where the matter has previously been addressed. For the same reason, IEEE does not respond to interpretation requests. Any person who would like to participate in evaluating comments or in revisions to an IEEE standard is welcome to join the relevant IEEE working group. You can indicate interest in a working group using the Interests tab in the Manage Profile & Interests area of the [IEEE SA myProject system](https://development.standards.ieee.org/myproject-web/public/view.html#landing).[^1] An IEEE Account is needed to access the application. -Comments on standards should be submitted using the [Contact Us](https://development.standards.ieee.org/myproject-web/public/view.html#landing) form.[^2] - -# Laws and regulations -{:.no-bookmark} - -Users of IEEE Standards documents should consult all applicable laws and regulations. Compliance with the provisions of any IEEE Standards document does not constitute compliance to any applicable regulatory requirements. Implementers of the standard are responsible for observing or referring to the applicable regulatory requirements. IEEE does not, by the publication of its standards, intend to urge action that is not in compliance with applicable laws, and these documents may not be construed as doing so. - -# Data privacy -{:.no-bookmark} - -Users of IEEE Standards documents should evaluate the standards for considerations of data privacy and data ownership in the context of assessing and using the standards in compliance with applicable laws and regulations. - -# Copyrights -{:.no-bookmark} - -IEEE draft and approved standards are copyrighted by IEEE under US and international copyright laws. They are made available by IEEE and are adopted for a wide variety of both public and private uses. These include both use, by reference, in laws and regulations, and use in private self-regulation, standardization, and the promotion of engineering practices and methods. By making these documents available for use and adoption by public authorities and private users, neither IEEE nor its licensors waive any rights in copyright to the documents. - -# Photocopies -{:.no-bookmark} - -Subject to payment of the appropriate licensing fees, IEEE will grant users a limited, non-exclusive license to photocopy portions of any individual standard for company or organizational internal use or individual, non-commercial use only. To arrange for payment of licensing fees, please contact Copyright Clearance Center, Customer Service, 222 Rosewood Drive, Danvers, MA 01923 USA; +1 978 750 8400; https://www.copyright.com/. Permission to photocopy portions of any individual standard for educational classroom use can also be obtained through the Copyright Clearance Center. - -# Updating of IEEE Standards documents -{:.no-bookmark} - -Users of IEEE Standards documents should be aware that these documents may be superseded at any time by the issuance of new editions or may be amended from time to time through the issuance of amendments, corrigenda, or errata. An official IEEE document at any point in time consists of the current edition of the document together with any amendments, corrigenda, or errata then in effect. -Every IEEE standard is subjected to review at least every 10 years. When a document is more than 10 years old and has not undergone a revision process, it is reasonable to conclude that its contents, although still of some value, do not wholly reflect the present state of the art. Users are cautioned to check to determine that they have the latest edition of any IEEE standard. -In order to determine whether a given document is the current edition and whether it has been amended through the issuance of amendments, corrigenda, or errata, visit [IEEE Xplore](https://ieeexplore.ieee.org/browse/standards/collection/ieee/) or [contact IEEE](https://standards.ieee.org/content/ieee-standards/en/about/contact/index.html).[^3] For more information about the IEEE SA or IEEE’s standards development process, visit the IEEE SA Website. -Errata -Errata, if any, for all IEEE standards can be accessed on the [IEEE SA Website](https://standards.ieee.org/standard/index.html).[^4] Search for standard number and year of approval to access the web page of the published standard. Errata links are located under the Additional Resources Details section. Errata are also available in [IEEE Xplore](https://ieeexplore.ieee.org/browse/standards/collection/ieee/). Users are encouraged to periodically check for errata. - -# Patents -{:.no-bookmark} - -IEEE Standards are developed in compliance with the [IEEE SA Patent Policy](https://standards.ieee.org/about/sasb/patcom/materials.html).[^5] - -Attention is called to the possibility that implementation of this standard may require use of subject matter covered by patent rights. By publication of this standard, no position is taken by the IEEE with respect to the existence or validity of any patent rights in connection therewith. If a patent holder or patent applicant has filed a statement of assurance via an Accepted Letter of Assurance, then the statement is listed on the IEEE SA Website at patents.html. Letters of Assurance may indicate whether the Submitter is willing or unwilling to grant licenses under patent rights without compensation or under reasonable rates, with reasonable terms and conditions that are demonstrably free of any unfair discrimination to applicants desiring to obtain such licenses. - -Essential Patent Claims may exist for which a Letter of Assurance has not been received. The IEEE is not responsible for identifying Essential Patent Claims for which a license may be required, for conducting inquiries into the legal validity or scope of Patents Claims, or determining whether any licensing terms or conditions provided in connection with submission of a Letter of Assurance, if any, or in any licensing agreements are reasonable or non-discriminatory. Users of this standard are expressly advised that determination of the validity of any patent rights, and the risk of infringement of such rights, is entirely their own responsibility. Further information may be obtained from the IEEE Standards Association. - -# IMPORTANT NOTICE -{:.no-bookmark} - -IEEE Standards do not guarantee or ensure safety, security, health, or environmental protection, or ensure against interference with or from other devices or networks. IEEE Standards development activities consider research and information presented to the standards development group in developing any safety recommendations. Other information about safety practices, changes in technology or technology implementation, or impact by peripheral systems also may be pertinent to safety considerations during implementation of the standard. Implementers and users of IEEE Standards documents are responsible for determining and complying with all appropriate safety, security, environmental, health, and interference protection practices and all applicable laws and regulations. - -[^1]: Available at: . -[^2]: Available at: . -[^3]: Available at: . -[^4]: Available at: . -[^5]: Available at: . - diff --git a/ieee-sa-standard-template/0-3-participants.md b/ieee-sa-standard-template/0-3-participants.md deleted file mode 100644 index 76033ddb..00000000 --- a/ieee-sa-standard-template/0-3-participants.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -style: frontmatter ---- - -# Participants - -At the time this draft <gde./rec. prac./std.> was completed, the <Working Group Name> Working Group had the following membership: - -| **AAA**, *Chair* -| **BBB**, *Vice Chair* -| **CCC**, *Secretary* -| **DDD**, *Technical Editor* -{:.table-no-border.table-no-padding.table-text-center} - -| Participant 1 | Participant 4 | Participant 7 | -| Participant 2 | Participant 5 | Participant 8 | -| Participant 3 | Participant 6 | Participant 9 | -{:.table-no-border.table-no-padding.table-columns-fixed} - -The following members of the <individual/entity> Standards Association balloting group voted on this <gde./rec. prac./std.>. Balloters may have voted for approval, disapproval, or abstention. - -***[To be supplied by IEEE]*** - -| Balloter 1 | Balloter 4 | Balloter 7 | -| Balloter 2 | Balloter 5 | Balloter 8 | -| Balloter 3 | Balloter 6 | Balloter 9 | -{:.table-no-border.table-no-padding.table-columns-fixed} - - -When the IEEE SA Standards Board approved this <gde./rec. prac./std.> on <date>, it had the following membership: - -***[To be supplied by IEEE]*** - -| **AAA**, *Chair* -| **BBB**, *Vice Chair* -| **CCC**, *Past Chair* -| **DDD**, *Secretary* -{:.table-no-border.table-no-padding.table-text-center} - -| SB Member 1 | SB Member 4 | SB Member 7 | -| SB Member 2 | SB Member 5 | SB Member 8 | -| SB Member 3 | SB Member 6 | SB Member 9 | -{:.table-no-border.table-no-padding.table-columns-fixed} -*Member Emeritus diff --git a/ieee-sa-standard-template/0-4-introduction.md b/ieee-sa-standard-template/0-4-introduction.md deleted file mode 100644 index d32b37bb..00000000 --- a/ieee-sa-standard-template/0-4-introduction.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -style: frontmatter ---- - -# Introduction - -| This introduction is not part of IEEE P<designation>/D<draft_number>, Draft <Gde./Rec. Prac./Std.> for <Complete Title Matching PAR>. - -Add introduction text here. - -# Acknowledgments - -In case the standard incorporates specific contributions of individuals or organizations, these can be listed and acknowledged here. diff --git a/ieee-sa-standard-template/0-5-contents.md b/ieee-sa-standard-template/0-5-contents.md deleted file mode 100644 index e7b45b9c..00000000 --- a/ieee-sa-standard-template/0-5-contents.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -title: Contents -style: contents-page ---- - -# Contents - -{% include toc %} diff --git a/ieee-sa-standard-template/01.md b/ieee-sa-standard-template/01.md deleted file mode 100644 index ab02f764..00000000 --- a/ieee-sa-standard-template/01.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -style: chapter no-header ---- - -{% include metadata %} - -{{ title }} -{:.title} - -# 1. Overview - -## 1.1 Scope - -Describe the scope of the standard here. - -## 1.2 Purpose - -Describe the purpose of the standard here. - -## 1.3 Word usage - -The word *shall* indicates mandatory requirements strictly to be followed in order to conform to the standard and from which no deviation is permitted (*shall* equals *is required to*).[^fn1], [^fn2] - -The word *should* indicates that among several possibilities one is recommended as particularly suitable, without mentioning or excluding others; or that a certain course of action is preferred but not necessarily required (*should* equals *is recommended that*). - -The word *may* is used to indicate a course of action permissible within the limits of the standard (*may* equals *is permitted to*). - -The word *can* is used for statements of possibility and capability, whether material, physical, or causal (*can* equals *is able to*). - -[^fn1]: The use of the word *must* is deprecated and cannot be used when stating mandatory requirements; *must* is used only to describe unavoidable situations. -[^fn2]: The use of *will* is deprecated and cannot be used when stating mandatory requirements; *will* is only used in statements of fact. diff --git a/ieee-sa-standard-template/02.md b/ieee-sa-standard-template/02.md deleted file mode 100644 index 74350dc0..00000000 --- a/ieee-sa-standard-template/02.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -style: chapter ---- - -# 2. Normative references - -The following referenced documents are indispensable for the application of this document (i.e., they must be understood and used, so each referenced document is cited in text and its relationship to this document is explained). For dated references, only the edition cited applies. For undated references, the latest edition of the referenced document (including any amendments or corrigenda) applies. diff --git a/ieee-sa-standard-template/03.md b/ieee-sa-standard-template/03.md deleted file mode 100644 index 91c29403..00000000 --- a/ieee-sa-standard-template/03.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -style: chapter ---- - -# 3. Definitions, acronyms, and abbreviations - -For the purposes of this document, the following terms and definitions apply. The IEEE Standards Dictionary Online should be consulted for terms not defined in this clause.[^fn3] - -## 3.1 Definitions - -Add definitions here. - -[^fn3]: IEEE Standards Dictionary Online is available at [https://ieeexplore.ieee.org](https://ieeexplore.ieee.org). diff --git a/ieee-sa-standard-template/04.md b/ieee-sa-standard-template/04.md deleted file mode 100644 index 5e6ca548..00000000 --- a/ieee-sa-standard-template/04.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -style: chapter ---- - -# 4. Body of the standard - -The normative text of the standard starts here. - -Example of reference to [Clause 1](01.html) and reference to [3.1](03.html#31-definitions). - -{% comment %} -Inline comments for the author of the document -{% endcomment %} diff --git a/ieee-sa-standard-template/a.md b/ieee-sa-standard-template/a.md deleted file mode 100644 index a059ee8a..00000000 --- a/ieee-sa-standard-template/a.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -style: annex ---- - -# Annex A **(informative)** Title - -Annex page template. diff --git a/ieee-sa-standard-template/styles/app.scss b/ieee-sa-standard-template/styles/app.scss deleted file mode 100644 index fb025074..00000000 --- a/ieee-sa-standard-template/styles/app.scss +++ /dev/null @@ -1,53 +0,0 @@ ---- -# App styles ---- - -// What is this? -// ------------- -// This file assembles the design and typography for this book. -// It inherits the variables set in the project's _sass folder. -// You can override those variables by using them here, -// without the `!default` that sets the default value in _sass. -// -// How to use it -// ------------- -// For book-specific styles (i.e. not project defaults): -// 1. Copy variables you want to override from _sass/app.scss, -// and remove `!default` to override the project default. -// 2. Add book-specific font imports below. -// 3. Add your own custom CSS or Sass at the bottom. - - -// ------------- -// Set variables -// ------------- - -// Edition suffix: identifies this edition in certain classes (e.g. in _epub-fitting.scss). -$edition-suffix: null; - - -// ------------ -// Import fonts -// ------------ - -// Add @font-face rules for fonts you specify here. -// Add the actual font files to `../fonts` or `../../assets/fonts`. -// Use #{$path-to-root-directory} to allow overriding per translation. E.g.: -// `src: url(#{$path-to-root-directory}/assets/fonts/CrimsonPro-Regular.ttf);` -// For snippets, try https://github.com/arthurattwell/font-faces - - -// ------------- -// Master theme -// ------------- - -// Import default project styles -@import 'template/app'; - - -// ------------- -// Custom styles -// ------------- - -// Add any custom Sass or CSS here. - diff --git a/ieee-sa-standard-template/styles/epub.scss b/ieee-sa-standard-template/styles/epub.scss deleted file mode 100644 index 630498b0..00000000 --- a/ieee-sa-standard-template/styles/epub.scss +++ /dev/null @@ -1,52 +0,0 @@ ---- -# EPUB styles ---- - -// What is this? -// ------------- -// This file assembles the design and typography for this book. -// It inherits the variables set in the project's _sass folder. -// You can override those variables by using them here, -// without the `!default` that sets the default value in _sass. -// -// How to use it -// ------------- -// For book-specific styles (i.e. not project defaults): -// 1. Copy variables you want to override from _sass/epub.scss, -// and remove `!default` to override the project default. -// 2. Add book-specific font imports below. -// 3. Add your own custom CSS or Sass at the bottom. - - -// ------------- -// Set variables -// ------------- - -// Edition suffix: identifies this edition in certain classes (e.g. in _epub-fitting.scss). -$edition-suffix: null; - - -// ------------ -// Import fonts -// ------------ - -// If you're embedding epub fonts, add @font-face rules -// for fonts you specify here. -// Add the actual font files to `_epub/fonts`. -// For snippets, try https://github.com/arthurattwell/font-faces - - -// ------------- -// Master theme -// ------------- - -// Import master styles -@import 'template/epub'; - - -// ------------- -// Custom styles -// ------------- - -// Add any custom Sass or CSS here. - diff --git a/ieee-sa-standard-template/styles/hyphenation.dic b/ieee-sa-standard-template/styles/hyphenation.dic deleted file mode 100644 index a423e6fa..00000000 --- a/ieee-sa-standard-template/styles/hyphenation.dic +++ /dev/null @@ -1,8 +0,0 @@ ---- -# This YAML frontmatter makes Jekyll process this file. -# So you can use Liquid tags to include files such as -# other hyphenation dictionaries, e.g. -# `{% include_relative hyph-en-gb.pat %}` -# or to use hyphenation in certain cases, e.g. variants. ---- - diff --git a/ieee-sa-standard-template/styles/print-pdf.scss b/ieee-sa-standard-template/styles/print-pdf.scss deleted file mode 100644 index d41f0a95..00000000 --- a/ieee-sa-standard-template/styles/print-pdf.scss +++ /dev/null @@ -1,58 +0,0 @@ ---- -# Print styles ---- - -// What is this? -// ------------- -// This file assembles the design and typography for this book. -// It inherits the variables set in the project's _sass folder. -// You can override those variables by using them here, -// without the `!default` that sets the default value in _sass. -// -// How to use it -// ------------- -// For book-specific styles (i.e. not project defaults): -// 1. Copy variables you want to override from _sass/print-pdf.scss, -// and remove `!default` to override the project default. -// 2. Add book-specific font imports below. -// 3. Add your own custom CSS or Sass at the bottom. - - -// ------------- -// Set variables -// ------------- - -// Edition suffix: identifies this edition in page-fitting classes (in _print-fitting.scss). -// For instance, a .tighten class in HTML might apply to your bookshop edition, but not the schools edition. -// A suffix '-schools-edn' would mean only tags with that suffix would apply to that edition, e.g. {:.tighten-schools-edn} -// If you're only planning one edition and use default tags ({:.tighten} not {:.tighten-schools-edn}), leave as null. -$edition-suffix: null; - - -// ------------ -// Import fonts -// ------------ - -// Add @font-face rules for fonts you specify here. -// Add the actual font files to `../fonts` or `../../assets/fonts`. -// Use #{$path-to-root-directory} to allow overriding per translation. E.g.: -// `src: url(#{$path-to-root-directory}/assets/fonts/CrimsonPro-Regular.ttf);` -// For snippets, try https://github.com/arthurattwell/font-faces -// By default, a print-font-faces partial will include rules -// for Crimson Pro, Source Sans Pro, and Ubuntu Mono. - - -// ------------- -// Master theme -// ------------- - -// Import master styles -@import 'template/print-pdf'; - - -// ------------- -// Custom styles -// ------------- - -// Add any custom Sass or CSS here. - diff --git a/ieee-sa-standard-template/styles/screen-pdf.scss b/ieee-sa-standard-template/styles/screen-pdf.scss deleted file mode 100644 index 2b4b1536..00000000 --- a/ieee-sa-standard-template/styles/screen-pdf.scss +++ /dev/null @@ -1,58 +0,0 @@ ---- -# Screen PDF styles ---- - -// What is this? -// ------------- -// This file assembles the design and typography for this book. -// It inherits the variables set in the project's _sass folder. -// You can override those variables by using them here, -// without the `!default` that sets the default value in _sass. -// -// How to use it -// ------------- -// For book-specific styles (i.e. not project defaults): -// 1. Copy variables you want to override from _sass/screen-pdf.scss, -// and remove `!default` to override the project default. -// 2. Add book-specific font imports below. -// 3. Add your own custom CSS or Sass at the bottom. - - -// ------------- -// Set variables -// ------------- - -// Edition suffix: identifies this edition in page-fitting classes (in _print-fitting.scss). -// For instance, a .tighten class in HTML might apply to your bookshop edition, but not the schools edition. -// A suffix '-schools-edn' would mean only tags with that suffix would apply to that edition, e.g. {:.tighten-schools-edn} -// If you're only planning one edition and use default tags ({:.tighten} not {:.tighten-schools-edn}), leave as null. -$edition-suffix: null; - - -// ------------ -// Import fonts -// ------------ - -// Add @font-face rules for fonts you specify here. -// Add the actual font files to `../fonts` or `../../assets/fonts`. -// Use #{$path-to-root-directory} to allow overriding per translation. E.g.: -// `src: url(#{$path-to-root-directory}/assets/fonts/CrimsonPro-Regular.ttf);` -// For snippets, try https://github.com/arthurattwell/font-faces -// By default, a print-font-faces partial will include rules -// for Crimson Pro, Source Sans Pro, and Ubuntu Mono. - - -// ------------- -// Master theme -// ------------- - -// Import master styles -@import 'template/screen-pdf'; - - -// ------------- -// Custom styles -// ------------- - -// Add any custom Sass or CSS here. - diff --git a/ieee-sa-standard-template/styles/web.scss b/ieee-sa-standard-template/styles/web.scss deleted file mode 100644 index 8ad54f00..00000000 --- a/ieee-sa-standard-template/styles/web.scss +++ /dev/null @@ -1,51 +0,0 @@ ---- -# Web styles ---- - -// What is this? -// ------------- -// This file assembles the design and typography for this book. -// It inherits the variables set in the project's _sass folder. -// You can override those variables by using them here, -// without the `!default` that sets the default value in _sass. -// -// How to use it -// ------------- -// For book-specific styles (i.e. not project defaults): -// 1. Copy variables you want to override from _sass/web.scss, -// and remove `!default` to override the project default. -// 2. Add book-specific font imports below. -// 3. Add your own custom CSS or Sass at the bottom. - - -// ------------- -// Set variables -// ------------- - -// Edition suffix: identifies this edition in certain classes (e.g. in _epub-fitting.scss). -$edition-suffix: null; - - -// ------------ -// Import fonts -// ------------ - -// Add @font-face rules for fonts you specify here. -// Add the actual font files to `../fonts` -// For snippets, try https://github.com/arthurattwell/font-faces - - -// ------------- -// Master theme -// ------------- - -// Import master styles -@import 'template/web'; - - -// ------------- -// Custom styles -// ------------- - -// Add any custom Sass or CSS here. - diff --git a/ieee-sa-standards-style-manual/images/screen-pdf/cover.jpg b/ieee-sa-standards-style-manual/images/screen-pdf/cover.jpg deleted file mode 100644 index 1bdd1899..00000000 Binary files a/ieee-sa-standards-style-manual/images/screen-pdf/cover.jpg and /dev/null differ diff --git a/ieee-sa-standards-style-manual/styles/app.scss b/ieee-sa-standards-style-manual/styles/app.scss deleted file mode 100644 index fb025074..00000000 --- a/ieee-sa-standards-style-manual/styles/app.scss +++ /dev/null @@ -1,53 +0,0 @@ ---- -# App styles ---- - -// What is this? -// ------------- -// This file assembles the design and typography for this book. -// It inherits the variables set in the project's _sass folder. -// You can override those variables by using them here, -// without the `!default` that sets the default value in _sass. -// -// How to use it -// ------------- -// For book-specific styles (i.e. not project defaults): -// 1. Copy variables you want to override from _sass/app.scss, -// and remove `!default` to override the project default. -// 2. Add book-specific font imports below. -// 3. Add your own custom CSS or Sass at the bottom. - - -// ------------- -// Set variables -// ------------- - -// Edition suffix: identifies this edition in certain classes (e.g. in _epub-fitting.scss). -$edition-suffix: null; - - -// ------------ -// Import fonts -// ------------ - -// Add @font-face rules for fonts you specify here. -// Add the actual font files to `../fonts` or `../../assets/fonts`. -// Use #{$path-to-root-directory} to allow overriding per translation. E.g.: -// `src: url(#{$path-to-root-directory}/assets/fonts/CrimsonPro-Regular.ttf);` -// For snippets, try https://github.com/arthurattwell/font-faces - - -// ------------- -// Master theme -// ------------- - -// Import default project styles -@import 'template/app'; - - -// ------------- -// Custom styles -// ------------- - -// Add any custom Sass or CSS here. - diff --git a/ieee-sa-standards-style-manual/styles/epub.scss b/ieee-sa-standards-style-manual/styles/epub.scss deleted file mode 100644 index 630498b0..00000000 --- a/ieee-sa-standards-style-manual/styles/epub.scss +++ /dev/null @@ -1,52 +0,0 @@ ---- -# EPUB styles ---- - -// What is this? -// ------------- -// This file assembles the design and typography for this book. -// It inherits the variables set in the project's _sass folder. -// You can override those variables by using them here, -// without the `!default` that sets the default value in _sass. -// -// How to use it -// ------------- -// For book-specific styles (i.e. not project defaults): -// 1. Copy variables you want to override from _sass/epub.scss, -// and remove `!default` to override the project default. -// 2. Add book-specific font imports below. -// 3. Add your own custom CSS or Sass at the bottom. - - -// ------------- -// Set variables -// ------------- - -// Edition suffix: identifies this edition in certain classes (e.g. in _epub-fitting.scss). -$edition-suffix: null; - - -// ------------ -// Import fonts -// ------------ - -// If you're embedding epub fonts, add @font-face rules -// for fonts you specify here. -// Add the actual font files to `_epub/fonts`. -// For snippets, try https://github.com/arthurattwell/font-faces - - -// ------------- -// Master theme -// ------------- - -// Import master styles -@import 'template/epub'; - - -// ------------- -// Custom styles -// ------------- - -// Add any custom Sass or CSS here. - diff --git a/ieee-sa-standards-style-manual/styles/hyphenation.dic b/ieee-sa-standards-style-manual/styles/hyphenation.dic deleted file mode 100644 index a423e6fa..00000000 --- a/ieee-sa-standards-style-manual/styles/hyphenation.dic +++ /dev/null @@ -1,8 +0,0 @@ ---- -# This YAML frontmatter makes Jekyll process this file. -# So you can use Liquid tags to include files such as -# other hyphenation dictionaries, e.g. -# `{% include_relative hyph-en-gb.pat %}` -# or to use hyphenation in certain cases, e.g. variants. ---- - diff --git a/ieee-sa-standards-style-manual/styles/print-pdf.scss b/ieee-sa-standards-style-manual/styles/print-pdf.scss deleted file mode 100644 index d41f0a95..00000000 --- a/ieee-sa-standards-style-manual/styles/print-pdf.scss +++ /dev/null @@ -1,58 +0,0 @@ ---- -# Print styles ---- - -// What is this? -// ------------- -// This file assembles the design and typography for this book. -// It inherits the variables set in the project's _sass folder. -// You can override those variables by using them here, -// without the `!default` that sets the default value in _sass. -// -// How to use it -// ------------- -// For book-specific styles (i.e. not project defaults): -// 1. Copy variables you want to override from _sass/print-pdf.scss, -// and remove `!default` to override the project default. -// 2. Add book-specific font imports below. -// 3. Add your own custom CSS or Sass at the bottom. - - -// ------------- -// Set variables -// ------------- - -// Edition suffix: identifies this edition in page-fitting classes (in _print-fitting.scss). -// For instance, a .tighten class in HTML might apply to your bookshop edition, but not the schools edition. -// A suffix '-schools-edn' would mean only tags with that suffix would apply to that edition, e.g. {:.tighten-schools-edn} -// If you're only planning one edition and use default tags ({:.tighten} not {:.tighten-schools-edn}), leave as null. -$edition-suffix: null; - - -// ------------ -// Import fonts -// ------------ - -// Add @font-face rules for fonts you specify here. -// Add the actual font files to `../fonts` or `../../assets/fonts`. -// Use #{$path-to-root-directory} to allow overriding per translation. E.g.: -// `src: url(#{$path-to-root-directory}/assets/fonts/CrimsonPro-Regular.ttf);` -// For snippets, try https://github.com/arthurattwell/font-faces -// By default, a print-font-faces partial will include rules -// for Crimson Pro, Source Sans Pro, and Ubuntu Mono. - - -// ------------- -// Master theme -// ------------- - -// Import master styles -@import 'template/print-pdf'; - - -// ------------- -// Custom styles -// ------------- - -// Add any custom Sass or CSS here. - diff --git a/ieee-sa-standards-style-manual/styles/screen-pdf.scss b/ieee-sa-standards-style-manual/styles/screen-pdf.scss deleted file mode 100644 index 2b4b1536..00000000 --- a/ieee-sa-standards-style-manual/styles/screen-pdf.scss +++ /dev/null @@ -1,58 +0,0 @@ ---- -# Screen PDF styles ---- - -// What is this? -// ------------- -// This file assembles the design and typography for this book. -// It inherits the variables set in the project's _sass folder. -// You can override those variables by using them here, -// without the `!default` that sets the default value in _sass. -// -// How to use it -// ------------- -// For book-specific styles (i.e. not project defaults): -// 1. Copy variables you want to override from _sass/screen-pdf.scss, -// and remove `!default` to override the project default. -// 2. Add book-specific font imports below. -// 3. Add your own custom CSS or Sass at the bottom. - - -// ------------- -// Set variables -// ------------- - -// Edition suffix: identifies this edition in page-fitting classes (in _print-fitting.scss). -// For instance, a .tighten class in HTML might apply to your bookshop edition, but not the schools edition. -// A suffix '-schools-edn' would mean only tags with that suffix would apply to that edition, e.g. {:.tighten-schools-edn} -// If you're only planning one edition and use default tags ({:.tighten} not {:.tighten-schools-edn}), leave as null. -$edition-suffix: null; - - -// ------------ -// Import fonts -// ------------ - -// Add @font-face rules for fonts you specify here. -// Add the actual font files to `../fonts` or `../../assets/fonts`. -// Use #{$path-to-root-directory} to allow overriding per translation. E.g.: -// `src: url(#{$path-to-root-directory}/assets/fonts/CrimsonPro-Regular.ttf);` -// For snippets, try https://github.com/arthurattwell/font-faces -// By default, a print-font-faces partial will include rules -// for Crimson Pro, Source Sans Pro, and Ubuntu Mono. - - -// ------------- -// Master theme -// ------------- - -// Import master styles -@import 'template/screen-pdf'; - - -// ------------- -// Custom styles -// ------------- - -// Add any custom Sass or CSS here. - diff --git a/ieee-sa-standards-style-manual/styles/web.scss b/ieee-sa-standards-style-manual/styles/web.scss deleted file mode 100644 index 8ad54f00..00000000 --- a/ieee-sa-standards-style-manual/styles/web.scss +++ /dev/null @@ -1,51 +0,0 @@ ---- -# Web styles ---- - -// What is this? -// ------------- -// This file assembles the design and typography for this book. -// It inherits the variables set in the project's _sass folder. -// You can override those variables by using them here, -// without the `!default` that sets the default value in _sass. -// -// How to use it -// ------------- -// For book-specific styles (i.e. not project defaults): -// 1. Copy variables you want to override from _sass/web.scss, -// and remove `!default` to override the project default. -// 2. Add book-specific font imports below. -// 3. Add your own custom CSS or Sass at the bottom. - - -// ------------- -// Set variables -// ------------- - -// Edition suffix: identifies this edition in certain classes (e.g. in _epub-fitting.scss). -$edition-suffix: null; - - -// ------------ -// Import fonts -// ------------ - -// Add @font-face rules for fonts you specify here. -// Add the actual font files to `../fonts` -// For snippets, try https://github.com/arthurattwell/font-faces - - -// ------------- -// Master theme -// ------------- - -// Import master styles -@import 'template/web'; - - -// ------------- -// Custom styles -// ------------- - -// Add any custom Sass or CSS here. - diff --git a/package.json b/package.json index f951635b..c60b84bd 100644 --- a/package.json +++ b/package.json @@ -72,7 +72,7 @@ ] }, "prince": { - "version": "books-20220701", + "version": "15", "license": "_prince/license.dat" } } diff --git a/setup.sh b/setup.sh deleted file mode 100755 index ce30aabc..00000000 --- a/setup.sh +++ /dev/null @@ -1,106 +0,0 @@ -# Main dependency installation - -mkdir download -cd download - -sudo apt-get update && apt-get install -y \ - software-properties-common \ - apt-transport-https \ - make \ - gcc \ - build-essential \ - git \ - wget \ - libgif7 \ - libpixman-1-0 \ - libffi-dev \ - libreadline-dev \ - zlib1g-dev \ - graphicsmagick \ - dos2unix \ - ruby-full - -# Dependencies specifically for Puppeteer on unix -sudo apt-get install -y \ - libasound2 \ - libatk1.0-0 \ - libatk-bridge2.0-0 \ - libcairo2 \ - libdrm2 \ - libgbm1 \ - libnss3 \ - libpango-1.0-0 \ - libxkbcommon-x11-0 \ - libxcomposite1 \ - libxdamage1 \ - libxfixes3 \ - libxrandr2 \ - curl \ - git - -# Install nodejs 20.x -sudo curl -k -sL https://deb.nodesource.com/setup_20.x > node_setup.sh -sudo bash node_setup.sh -sudo apt-get install nodejs -y - -# Install libssl1.1 -wget http://archive.ubuntu.com/ubuntu/pool/main/o/openssl/libssl1.1_1.1.0g-2ubuntu4_amd64.deb -sudo dpkg -i libssl1.1_1.1.0g-2ubuntu4_amd64.deb - -# Install libgif7 -wget http://archive.ubuntu.com/ubuntu/pool/main/g/giflib/libgif7_5.1.2-0.2_amd64.deb -sudo dpkg -i libgif7_5.1.2-0.2_amd64.deb - -# Install PrinceXML for printing to PDF -wget --no-check-certificate https://www.princexml.com/download/prince_11.4-1_ubuntu18.04_amd64.deb -sudo dpkg -i prince_11.4-1_ubuntu18.04_amd64.deb - -# Install pandoc for document conversion -wget https://github.com/jgm/pandoc/releases/download/2.5/pandoc-2.5-1-amd64.deb -sudo dpkg -i ./pandoc-2.5-1-amd64.deb - -# Install vscode -wget -O- https://packages.microsoft.com/keys/microsoft.asc | sudo gpg --dearmor | sudo tee /usr/share/keyrings/vscode.gpg -echo deb [arch=amd64 signed-by=/usr/share/keyrings/vscode.gpg] https://packages.microsoft.com/repos/vscode stable main | sudo tee /etc/apt/sources.list.d/vscode.list -sudo apt update -sudo apt install code - -# Install chrome -wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb -sudo dpkg -i google-chrome-stable_current_amd64.deb - -# Update npm -sudo npm install -g npm@latest - -# Install Gulp cli app -sudo npm install --global gulp-cli - -cd .. - -# Set paths for Ruby gems -echo '# Define Ruby Gems path to ~/gems' >> ~/.bashrc -echo 'export GEM_HOME="$HOME/gems"' >> ~/.bashrc -echo 'export PATH="$HOME/gems/bin:$PATH"' >> ~/.bashrc -source ~/.bashrc - -# Install bundler and jekyll -sudo gem install jekyll bundler - -# install gems -sudo bundle install - -# you might need this to resolve version conficts -#bundle update --bundler -#bundle install -#bundle update -#bundle clean --force - -# Install Microsoft Core Fonts -echo ttf-mscorefonts-installer msttcorefonts/accepted-mscorefonts-eula select true | sudo debconf-set-selections -sudo apt-get install ttf-mscorefonts-installer -y - -# due to zscaler, disable CA check -export NODE_TLS_REJECT_UNAUTHORIZED=0 - -# Install local npm packages for EBW -npm i