feat: move builder to develop and tutorials to learn

_layouts/tutorial.html → _layouts/learn.html

@@ -1,10 +1,10 @@
 ---
 layout: docs-base
 html-class: docs-page
-docs_title: Introduction to Metanorma tutorial
+docs_title: Learning Metanorma
 
 navigation:
-  base_url: /tutorial
+  base_url: /learn
   items:
     - title: Lesson 1 - Introduction to Metanorma
       path: /lessons/lesson-1/

_pages/contribute.adoc

@@ -14,7 +14,7 @@ The Metanorma core code and related projects are all hosted
 at the https://github.com/metanorma[Metanorma GitHub organization]
 as open-source software.
 
-Any contribution (bugfixes, enhancements) would be much appreciated.
+Any contribution (bugfixes, enhancements) will be appreciated.
 
 NOTE: A number of Metanorma flavors are required to follow stringent rules
 set by SDO user organizations. Please understand that any changes that
@@ -24,17 +24,10 @@ SDO approval.
 
 == For technical writers
 
-Metanorma has applied for support from the
-https://developers.google.com/season-of-docs[Google Seasons of Docs]
-program.
-
-We are committed to making the application process and participation
-accessible to everyone -- please feel free to reach out and we will
-do our best to accommodate your needs.
-
-If you are interested in participating in the GSoD program for Metanorma,
-please apply at the https://github.com/metanorma/discussions/discussions[Discussions page]
+If you are interested in contributing to Metanorma as a technical writer,
+contact us on the
+https://github.com/metanorma/discussions/discussions[Discussions page]
 or directly contact [email protected].
 
-The Metanorma GSoD 2021 proposal is available
-link:/blog/2021-03-26/metanorma-gsod-2021/[here].
+NOTE: The previous Metanorma GSoD 2021 program that has been concluded can be
+referenced link:/blog/2021-03-26/metanorma-gsod-2021/[here].

_pages/builder.adoc → _pages/develop.adoc

@@ -1,11 +1,18 @@
 ---
-layout: builder-docs
-title: Builder's documentation
+layout: develop-docs
+title: Developer documentation
 html-class: overview
-article_header_title: Builder's documentation
+article_header_title: Developer documentation
 ---
 :page-liquid:
 
+To build documents with Metanorma, you need to have the Metanorma
+command-line toolchain installed. See link:/install/develop[Development installation].
+
+The toolchain consists of `metanorma-cli` Ruby gem and its dependencies.
+
+In general, these installation methods are recommended.
+
 This documentation is aimed at those who are using Metanorma
 to build document authoring workflows for their organization.
 

_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.

_pages/docs.adoc

@@ -0,0 +1,33 @@
+---
+layout: docs-base
+html-class: docs-page
+title: Documentation
+---
+
+== New User
+
+image::/assets/author/beginner.svg[height=200px,alt="New user image"]
+
+link:/install[*Installation guide*: I want to install Metanorma.]
+
+link:/learn[*Learn*: I want to learn how to use Metanorma.]
+
+link:/author[Documentation*: I want to understand the concepts of Metanorma.]
+
+
+== Advanced User
+image::/assets/author/advanced_user.svg[alt="Advanced user image",height=200px]
+
+link:/author[Documentation*: I'm editing a Metanorma document and need help.]
+
+link:/references[Reference documentation*: I need to look up an attribute.]
+
+link:/flavors[Flavor documentation*: I need SDO specific information about Metanorma.]
+
+== Developer
+
+image::/assets/author/developer.svg[alt="Developer",height=200px]
+
+link:/develop[Developer documentation*: I want to create a new Metanorma flavor.]
+
+link:/contribute[Contribution guidelines*: I want to contribute to the Metanorma stack.]

_pages/flavors.adoc

@@ -63,7 +63,7 @@ NOTE: Some flavors are supported directly by user organizations.
 [TIP]
 ====
 If you want to use Metanorma to author a different kind of document, take a look
-at the customization guidelines in link:/builder/[Metanorma builder's documentation].
+at the customization guidelines in link:/develop/[Metanorma developer's documentation].
 ====
 
 == Experimental flavors

_pages/installation.adoc → _pages/install.adoc

@@ -39,16 +39,16 @@ continuous integration (CI) environments.
 * link:/software/metanorma-cli/[Ruby gem]
 +
 [TIP]
-.Manual installation
+.Development installation
 ====
 Assuming you know what you're doing, the
 https://rubygems.org/gems/metanorma-cli[metanorma-cli] gem can be manually
-installed.
+installed for development.
 
 You will have to take care of dependencies: an appropriate Ruby version,
 plus other software depending on the end documents you're building.
 
-Refer to link:/install/manual-installation[Metanorma CLI installation docs]
+Refer to the link:/install/develop[Development installation guide]
 for details.
 ====
 
@@ -286,14 +286,14 @@ on how to install the Ruby gem on its own.
 Follow the links for your level of expertise with Metanorma:
 [[new]]
 == New User
-If you are fairly new, follow these steps to get acquainted with our tool. 
+If you are fairly new, follow these steps to get acquainted with our tool.
 
 [[experienced]]
 == Experienced Users
-If you have already used Metanorma, then probably you'd like to directly navigate to the Authoring Guide. Follow these steps. 
+If you have already used Metanorma, then probably you'd like to directly navigate to the Authoring Guide. Follow these steps.
 
 [[expert]]
 == Expert
-If you are well-versed with the tool, probably you belong to the developer level. Follow these steps to navigate to Developer Docs. 
+If you are well-versed with the tool, probably you belong to the developer level. Follow these steps to navigate to Developer Docs.
 
 

_pages/install/manual-installation.adoc → _pages/install/develop.adoc

@@ -1,19 +1,19 @@
 ---
 layout: docs-base
 html-class: docs-page
-title: Manual Installation of Metanorma
+title: Development installation
 ---
-= Manual Installation of Metanorma
+= Development installation
 
 == General
 
-The `metanorma` command-line executable is installed by this Ruby gem.
+The `metanorma` command-line executable can be installed by manually
+installing the `metanorma-cli` Ruby gem.
 
 [IMPORTANT]
 ====
-Users of the Metanorma suite should install Metanorma according to the steps at
-the
-link:/author/topics/install/[Metanorma installation guide].
+Typical users should install Metanorma according to the steps at
+the link:/author/install/[Installation guide].
 
 The instructions provided here are intended for Metanorma developers, since
 a number of third-party dependencies will also need to be installed manually.
@@ -45,8 +45,7 @@ Once Ruby is installed, you can install `metanorma-cli` as a gem:
 gem install metanorma-cli
 ----
 
-Installing the gem will also install all officially supported Metanorma flavors
-(such as ISO, CalConnect, IETF, etc).
+Installing this gem will also install all publicly available Metanorma flavors.
 
 
 == Dependencies
@@ -63,22 +62,29 @@ Linux:: Follow https://www.java.com/en/download/help/linux_install.html[official
 
 Windows:: Run `choco install -y javaruntime`
 
-=== PlantUML
 
-*If your documents include link:/author/topics/document-format/diagrams/[PlantUML diagrams]*,
+=== PlantUML (optional)
+
+If your documents include
+link:/author/topics/document-format/diagrams/[PlantUML diagrams],
 PlantUML will have to be installed.
 
+Specifically, you must have an accessible executable called `plantuml` in your
+terminal path.
+
 macOS:: Run `brew install plantuml`.
 
-Linux:: Link the PlantUML jar file into a command line executable; see
-`.travis.yml` for an example.
+Linux:: Link the PlantUML jar file into a command line executable.
+Please refer to the https://plantuml.com[official PlantUML site] for
+installation instructions.
 
 Windows:: Run `choco install -y plantuml`.
 
 If PlantUML diagrams used within a document but there PlantUML is not installed,
 the PlantUML diagram source will be incorporated into the output document as
 source code (i.e. `[source]` style).
 
+
 === Graphviz
 
 Graphviz is required by LutaML (and PlantUML) to draw diagrams.
@@ -109,9 +115,9 @@ pip3 install xml2rfc
 ----
 
 
-=== Inkscape
+=== Inkscape (optional)
 
-Optional dependency. Inkscape is needed for SVG-to-EMF conversion functionality.
+Inkscape is needed for SVG-to-EMF conversion functionality.
 
 macOS:: Run `brew install inkscape`
 
@@ -120,9 +126,10 @@ Linux:: See Linux instructions https://inkscape.org/release/[here]
 Windows:: Run `choco install -y inkscape`
 
 
-=== LaTeXML
+=== LaTeXML (optional, deprecated)
 
-Optional dependency. `LaTeXML` is needed for Metanorma for LaTeX functionality.
+NOTE: `LaTeXML` was previously used by Metanorma for LaTeX functionality
+but Plurimath now handles all LaTeX math processing.
 
 Most of the packages from various package manager listed on
 https://dlmf.nist.gov/LaTeXML/get.html are outdated.
@@ -138,7 +145,7 @@ cpanm --notest LaTeXML
 cpanm --notest git://github.com/brucemiller/LaTeXML.git@9a0e7dc5
 ----
 
-Alternative, it also can be installed in the following ways (always check the
+Alternatively, it also can be installed in the following ways (always check the
 version, because the packages may be outdated):
 
 macOS:: Run `brew install latexml`

_pages/learn.adoc

@@ -0,0 +1,41 @@
+---
+layout: learn
+title: Learn Metanorma
+description: A series of tutorials to get you familiar with Metanorma.
+---
+
+NOTE: If you are completely unfamiliar with Metanorma, you've come to the right
+place.
+
+This is a gentle introduction to Metanorma for first-time users.
+
+The course is as *flavor-agnostic* as possible and serves as a general
+introduction to Metanorma.
+
+You will learn about:
+
+* Foundations of using Metanorma
+* Creating documents
+* Compiling documents
+* Troubleshooting basics
+
+== Prerequisites
+
+* https://www.metanorma.org/install/[Install Metanorma]
++
+TIP: Use Metanorma in Docker to get started faster.
+
+* Download the https://github.com/metanorma/metanorma-tutorial[Metanorma tutorial project].
+
+link:/learn/lessons/lesson-1/">Start tutorial »</a></div>
++++
+
+== After the course
+
+After you've completed the course, you will be ready to create Metanorma
+documents on your own.
+
+To get started, you can download a
+https://github.com/orgs/metanorma/repositories?q=mn-templates[template document].
+
+Look up any flavor-specific rules in the the link:/flavors[flavor documentation].