chore: content fixes

metanorma · Mar 6, 2024 · f2e5743 · f2e5743
1 parent 9d8443f
commit f2e5743
Show file tree

Hide file tree

Showing 35 changed files with 265 additions and 245 deletions.
diff --git a/.lycheeignore b/.lycheeignore
@@ -9,4 +9,5 @@ ldap://.*
 http://www.idpf.org/2007/ops
 # These links are due to redirect_from and cannot be fixed
 https://www.metanorma.org/developer/
-https://www.metanorma.org/installation/
+https://www.metanorma.org/installation/
+https://www.metanorma.org/install/
diff --git a/_pages/developer.adoc b/_pages/developer.adoc
@@ -6,7 +6,7 @@ redirect_from:
   - /developer/
 ---
 
-= Developer documentation
+== Developer documentation
 
 To build documents with Metanorma, you need to have the Metanorma
 command-line toolchain installed.

diff --git a/_pages/learn.adoc b/_pages/learn.adoc
@@ -21,13 +21,13 @@ You will learn about:
 
 == Prerequisites
 
-* https://www.metanorma.org/install/[Install Metanorma]
+* link:/install/[Install Metanorma]
 +
-TIP: Use Metanorma in Docker to get started faster.
+TIP: Use Metanorma in Docker to get started faster. 
+* Download the https://github.com/metanorma/metanorma-tutorial[Metanorma tutorial project]. 
 
-* Download the https://github.com/metanorma/metanorma-tutorial[Metanorma tutorial project].
-
-link:/learn/lessons/lesson-1/">Start tutorial »</a></div>
++++
+<div class="cta tutorial"><a class="button" href="/learn/lessons/lesson-1/">Start tutorial »</a></div>
 +++
 
 == After the course

diff --git a/_sass/metanorma-rules.scss b/_sass/metanorma-rules.scss
@@ -68,12 +68,6 @@ body.overview section.documentation {
   }
 }
 
-.cta .button .tutorial {
-  @include cta-button($primary-dark-color, #ffffff);
-  border-radius: 25px;
-  &:hover {background-color: #9c60c1ff};
-}
-
 
 .web-build-ui {
   &.conditional {
@@ -296,3 +290,30 @@ body > .underlay > header {
     @include docs-page($primary-dark-color);
   }
 }
+
+/* Learn layout style */
+body.layout--learn {
+  article > header > nav.subitems {
+    display: none;
+  }
+
+  .ulist.checklist > ul.checklist {
+    list-style: none;
+  }
+
+  .cta.tutorial {
+    .button {
+      @include cta-button($primary-dark-color, #ffffff);
+      border-radius: 25px;
+      &:hover {background-color: #9c60c1ff};
+    }
+  }
+
+
+  details {
+    summary.title {
+      background-color: #28388A !important;
+      &:hover {background-color: #9c60c1ff !important};
+    }
+  }
+}
diff --git a/author/ieee/authoring-guide/terms-definitions.adoc b/author/ieee/authoring-guide/terms-definitions.adoc
@@ -3,7 +3,7 @@ layout: ieee-flavor
 title: Terms and definitions
 ---
 ////
-This text is copied and pasted from metanorma.org:staging /tutorials/tutorial_complete.adoc
+This text is copied and pasted from metanorma.org:staging /learn/tutorial_complete.adoc
 Once staging is merged into main --> Reuse
 ////
 

diff --git a/author/ogc/authoring-guide/cross-references.adoc b/author/ogc/authoring-guide/cross-references.adoc
@@ -103,54 +103,3 @@ To reference an *external* source:
 ----
 http://www.iso.org/[International Organization for Standardization].
 ----
-
-== Internal references
-
-To link to an important section, table, figure, formula, or list item in your document:
-
-. Set an anchor using double square brackets before the content you want to reference: `\[[anchor]]`.
-+
-.Example for an anchor preceding an image
-[source,adoc]
-----
-[[figureC-1]]
-.Typical gelatinization curve
-image::images/rice_image2.png[Image of the gelatinization curve]
-----
-+
-.Rendered image caption
-image::/assets/author/learn/references_img_anchor.jpg[]
-
-. To reference an anchor, type the anchor name like this `\<<anchor>>`.
-+
-[source,adoc]
-----
-<<figureC-1>> gives an example of a typical gelatinization curve.
-----
-+
-.Rendered reference
-image::/assets/author/learn/references_img_target.jpg[]
-
-. To set an alternative text other than the anchor text, append the text inside the brackets using a comma.
-+
-[source,adoc]
-----
-<<figureC-1, The diagram>> gives an example of a typical gelatinization curve.
-----
-
-=== Auto-numbering of references
-
-Metanorma automatically numbers and names references; because they are
-auto-numbered, they will be renumbered automatically if you insert any new text
-of the same type.
-
-Metanorma markup is serialized into XML, hence the anchor should follow the https://www.w3.org/TR/xml-names11/[XML namespace conventions].
-
-i.e., an anchor name name must not contain:
-
-* colons
-* whitespaces
-* words starting with numbers
-
-If you want to learn more about the technical aspects of cross-references, read
-link:/author/concepts/deep-dive-cross-references[Deep-dive into cross-references].
diff --git a/learn/lessons/exercises.adoc b/learn/lessons/exercises.adoc
@@ -4,13 +4,13 @@ https://shopify.github.io/liquid/tags/control-flow/
 ////
 :page-liquid:
 
-The code for this exercise is available on https://github.com/metanorma/metanorma-learn/tree/master/sources/standard[GitHub].
+The code for this exercise is available on https://github.com/metanorma/metanorma-tutorial/tree/master/sources/standard[GitHub]. 
 
 The corresponding file is named `{{include.content}}.adoc`
 
 {% case {{include.content}} %}
   {% when "exercise-2-1" %}
-Now it’s your turn. Fill the document with the following attributes:
+Now it’s your turn. Fill the document with the following attributes: 
 
 [%interactive]
 * [ ] Document title
@@ -25,14 +25,14 @@ Now it’s your turn. Fill the document with the following attributes:
 .Hint
 [%collapsible]
 ====
-To declare an attribute, follow the syntax `:attribute: value`.
+To declare an attribute, follow the syntax `:attribute: value`. 
 
 For example: `:publisher: Ribose Inc.`
-====
+==== 
 
   {% when "exercise-2-2" %}
-Look at the prepopulated Metanorma document.
-There are many clauses describing the content but there are sections missing to form a correct standard document.
+Look at the prepopulated Metanorma document. 
+There are many clauses describing the content but there are sections missing to form a correct standard document. 
 Add the following sections:
 
 [%interactive]
@@ -57,9 +57,9 @@ Add lists to the prepopulated document.
 ====
 Ordered list items start with a dot, followed by a blank: `. List item`.
 
-Unordered list items start with an asterisk, followed by a blank: `* List item`.
+Unordered list items start with an asterisk, followed by a blank: `* List item`. 
 
-To write a definition list, follow the syntax:
+To write a definition list, follow the syntax: 
 `term:: Definition`
 ====
 
@@ -119,7 +119,7 @@ The structure for a three column table looks like this:
   {% when "exercise-2-3-4" %}
 Insert a diagram of of a rice plant in line 17 by following the steps below:
 [%interactive]
-* [ ] Add an image macro.
+* [ ] Add an image macro.  
 * [ ] Populate the `image::` macro with this link: +
 ----
 https://en.wikipedia.org/wiki/Open_Geospatial_Consortium#/media/File:GeoServer_GeoNetwork_with_web_app.svg
@@ -136,7 +136,7 @@ Data stores:: Contain databases and shape files.
 .Hint
 [%collapsible]
 ====
-The syntax for images is: `image::URL[]`.
+The syntax for images is: `image::URL[]`. 
 
 Make sure to include the square brackets after the link.
 ====
@@ -156,15 +156,15 @@ To create admonitions that span several lines, you need to declare a block.
 ----
 [NOTE]
 ====
-This is a long note.
+This is a long note. 
 It contains three lines.
 Line three.
 ====
 ----
 ======
 
   {% when "exercise-2-3-6" %}
-There are some code samples in the document but they are not neatly packed into `source` blocks, so they cause trouble.
+There are some code samples in the document but they are not neatly packed into `source` blocks, so they cause trouble. 
 
 [%interactive]
 * [ ] Create a source block with the attribute `ruby` for the code in lines 20-35.
@@ -195,7 +195,7 @@ Format the text using the following formatting:
 * [ ] Add a footnote on line 30 to explain the OGC Innovation Program. Footnote text: See all active initatives at the OGC wesite. https://www.ogc.org/projects/initiatives/active.
 
   {% when "exercise-2-4-2" %}
-Let's add some index entries to the text.
+Let's add some index entries to the text. 
 [%interactive]
 * [ ] Add a visible index entry to "OGC" on line 25
 * [ ] Add an invisible three level index entry after "FAIR" on line 27: FAIR, findability, accessibility
@@ -213,13 +213,13 @@ Hidden index terms: `(\((Level 1 index term, Level 2 index term, Level 3 index t
   {% when "exercise-2-4-3" %}
 Let's add some references to the sample document.
 
-Internal references:
+Internal references: 
 [%interactive]
 * [ ] Create an anchor for the table called `tab-properties-of-the-descriptiontype-structure`
 * [ ] Replace the word "ANCHOR" in line 44 with a reference to the table.
 
-Bibliographic references:
-The text references some standards which don't have a matching entry in the bibliography section. Add the following bibliographic references:
+Bibliographic references: 
+The text references some standards which don't have a matching entry in the bibliography section. Add the following bibliographic references: 
 
 [%interactive]
 * [ ] dcat, W3C vocab-dcat, W3C: *Data Catalog Vocabulary,* W3C Recommendation 16 January 2014, https://www.w3.org/TR/vocab-dcat/
@@ -243,12 +243,12 @@ The text contains some typos. Mark the errors using comments.
 
   {% when "exercise-3-2" %}
 Let's check out what happens when we compile `exercise-3-2.adoc`
-To compile our document:
+To compile our document: 
 
 . Open a new terminal
 . Start Docker using Docker Desktop.
-. Go to the directory where your Metanorma document(s) are stored. For example:
-+
+. Go to the directory where your Metanorma document(s) are stored. For example: 
++ 
 [source,sh]
 ----
 $ cd Documents/Metanorma/metanorma-tutorial
@@ -273,15 +273,15 @@ docker run -v "%cd%":/metanorma/ -w /metanorma metanorma/metanorma metanorma com
 [%collapsible]
 ====
 . Relaton fetches checks the cited standards if it can fetch some information automatically.
-.
+. 
 ====
 
   {% when "exercise-4-2" %}
-The following document doesn't compile because there are some errors.
+The following document doesn't compile because there are some errors. 
 
 . Enter `metnanorma exercise-4-2.adoc` to trigger the build process.
-. Have a look at the error messages.
-. Try to debug the document. If you get stuck, have a look at the hints.
+. Have a look at the error messages. 
+. Try to debug the document. If you get stuck, have a look at the hints. 
 . Once you solved the errors, run the compilation command again to see if the document is build.
 
 .Hint Error 1
@@ -295,13 +295,13 @@ You can solve this error by renaming one of the anchors.
 [%collapsible]
 ====
 Line 76: The file that should be included cannot be found.
-Since the scope section already contains text, you can delete the reference.
+Since the scope section already contains text, you can delete the reference. 
 ====
 
 .Hint Error 3
 [%collapsible]
 ====
-Line 236: The image attribute contains a whitespace after `image::`, so the path is invalid. Delete the whitespace.
+Line 236: The image attribute contains a whitespace after `image::`, so the path is invalid. Delete the whitespace. 
 ====
   {% else %}
      Couldn't load exercise.

diff --git a/learn/lessons/lesson-1-1.adoc b/learn/lessons/lesson-1-1.adoc
@@ -5,7 +5,7 @@ title: What is Metanorma?
 == What you get is what you see vs. What you get is what you mean
 //include::/author/concepts/wysiwyg_vs_wysiwym.adoc[tag=tutorial]
 
-Word is probably your go-to application for casual writing, such as letters, invitations - and with good reason, because Word has many benefits, such as:
+Word is probably your go-to application for casual writing, such as letters, invitations - and with good reason, because Word has many benefits, such as: 
 
 * Creating documents quickly
 * An intuitive interface
@@ -16,9 +16,9 @@ image::/assets/author/concepts/word_WSYIWYG.png[Word is a WYSIWYG application]
 
 However, have you ever written a longer text, with many references, like a scientific text? Then you might have experienced some pain with Word: It tends to mess up the formatting, even if you use templates. Reference management in Word is also no fun, but the worst: Word tends to crash for very long documents, like standards.
 
-Because of these issues, another approach to creating documents is popular: “What you see is what you mean” (WYSIWYM). This concept differs from WYSIWYG because you separate the content and the layout into separate files. To tell the compiler how the text should look or behave, you use markup language. You may have heard about Markdown or LaTeX, which are popular markup languages, but Metanorma uses AsciiDoc.
+Because of these issues, another approach to creating documents is popular: “What you see is what you mean” (WYSIWYM). This concept differs from WYSIWYG because you separate the content and the layout into separate files. To tell the compiler how the text should look or behave, you use markup language. You may have heard about Markdown or LaTeX, which are popular markup languages, but Metanorma uses AsciiDoc. 
 
-The benefit is that you can publish different outputs from one source, for example into PDF or HTML. Since the layout is stored in a separate file, each output can even be styled differently.
+The benefit is that you can publish different outputs from one source, for example into PDF or HTML. Since the layout is stored in a separate file, each output can even be styled differently. 
 
 .Metanorma uses AsciiDoc text as an input and can deliver different outputs, such as PDF and HTML. A stylesheet determines how the outcome looks like.
 image::/assets/author/concepts/metanorma_WSYIWYM.png[What you see is what you mean]
@@ -28,12 +28,12 @@ image::/assets/author/concepts/metanorma_WSYIWYM.png[What you see is what you me
 
 Metanorma is actually not one thing, but three:
 
-. The Metanorma toolchain: This is the software that you use to create documents and generate output.
-. Document metamodels: Metanorma provides a document structure for standardization documents, specified in https://www.isotc154.org/projects/iso-36001/[ISO 36001]. Since each organization has different requirements for their standard documents, they use a https://www.metanorma.org/flavors/[“flavor”] of Metanorma. A flavor is a document model that provides additional metadata to reflect the SDO’s needs.
-. XML schemas: To use the defined document metamodels, there needs to be a machine-readable file so that documents can be checked against their intended structure.
+. The Metanorma toolchain: This is the software that you use to create documents and generate output. 
+. Document metamodels: Metanorma provides a document structure for standardization documents, specified in https://www.isotc154.org/projects/iso-36001/[ISO 36001]. Since each organization has different requirements for their standard documents, they use a https://www.metanorma.org/flavors/[“flavor”] of Metanorma. A flavor is a document model that provides additional metadata to reflect the SDO’s needs. 
+. XML schemas: To use the defined document metamodels, there needs to be a machine-readable file so that documents can be checked against their intended structure. 
 
 Metanorma consists of several layers of complexity, see the figure below.
-The basis for each metanorma document is AsciiDoc. Since AsciiDoc itself has limited functionalities for authoring standards, Metanorma extends AsciiDoc as one part of the Metanorma toolchain (1). Metanorma AsciiDoc provides advanced features, such as automatically linking the correct standard in a bibliography section.
+The basis for each metanorma document is AsciiDoc. Since AsciiDoc itself has limited functionalities for authoring standards, Metanorma extends AsciiDoc as one part of the Metanorma toolchain (1). Metanorma AsciiDoc provides advanced features, such as automatically linking the correct standard in a bibliography section. 
 The final layer of complexity are flavour-specific document rules and best practices based on the document metamodels (2). For example, ISO documents must include a "Scope" section, whereas NIST requires an "Acknowledgements" section.
 
 .Metanorma extends AsciiDoc provide a powerful tool for standard organizations
@@ -51,4 +51,6 @@ Metanorma has many advantages when you want to edit standards:
 
 Let’s explore the workflow of Metanorma in the next lesson.
 
-link:/learn/lessons/lesson-1-2/[Start next lesson »]
++++
+<div class="cta tutorial"><a class="button" href="/learn/lessons/lesson-1-2/">Start next lesson »</a></div>
++++