Merge pull request #77 from googlefonts/issue-37-extend-info-about-me…

…nu-bar

Extend info about menu bar

_explanations/designspace.md

@@ -0,0 +1,73 @@
+---
+title     : Designspace
+layout    : default
+permalink : /explanations/designspace/
+draft     : true
+order     : 901
+---
+
+<nav aria-label="breadcrumb">
+  <ol class="breadcrumb small">
+    <li class="breadcrumb-item"><a href="{{ site.url }}">Index</a></li>
+    <li class="breadcrumb-item"><a href="../../explanations">Explanations</a></li>
+    <li class="breadcrumb-item active" aria-current="page">{{ page.title }}</li>
+  </ol>
+</nav>
+
+We recommend spending some time with setting up your designspace properly. Questions you may ask yourself before you start with a new typeface:
+{: .lead }
+
+- What axes do your font project will end up with?
+  - [Registerd axes](https://learn.microsoft.com/en-us/typography/opentype/spec/dvaraxisreg#registered-axis-tags) like *Weight*, *Width*, *Italic*, *Optical size*
+  - or even a [non-registered axes (all uppercase tags)](https://fonts.google.com/variablefonts#axis-definitions?)
+- What ranges will these axes have?
+  - maybe *Weight* from 100 to 900 (Thin to Black)
+  - maybe *Width* from 75 to 150 (Condensed to Wide)
+- Do you plan to have *Italics*?
+  - Are the *Italics* real *Italics* (maybe use [Axis Type Discrete]({{ site.url }}/reference/menu/font/axes#range-axis-type-discrete))
+  - or are they interpolatable with the uprights, like Slanted? (maybe use [Axis Type Continuous]({{ site.url }}/reference/menu/font/axes#range-axis-type-continuous))
+- Which font instances are you planing to have?
+- Which font sources are required for this designspace?
+
+
+### Example:
+Let's imagine we want to create a typeface with the following axes:
+- **Weight** 100 to 900
+- **Width** 75 to 150
+
+#### Minimum of font sources required:
+  - Condensed Thin
+  - Condensed Black
+  - Wide Thin
+  - Wide Black
+
+(But keep in mind that you may need also intermediate sources to tweak the design somethere in between.)
+
+#### Number of font instances planned:
+  - Condensed Thin (width: 75, weight: 100)
+  - Condensed Light
+  - Condensed Regular (width: 75, weight: 400)
+  - Condensed Medium
+  - Condensed Bold
+  - Condensed Black (width: 75, weight: 900)
+  - Thin (width: 100, weight: 100)
+  - Light
+  - Regular (width: 100, weight: 400)
+  - Medium
+  - Bold
+  - Black (width: 100, weight: 900)
+  - Wide Thin (width: 150, weight: 100)
+  - Wide Light
+  - Wide Regular (width: 150, weight: 400)
+  - Wide Medium
+  - Wide Bold
+  - Wide Black (width: 150, weight: 900)
+
+
+Once you have sketched out your designspace, you're ready to create your [font axes]({{ site.url }}/reference/menu/font/axes).
+
+
+### Links
+
+- [Google Fonts: Designspace](https://fonts.google.com/knowledge/glossary/designspace)
+- [fonttools: designspaceLib](https://fonttools.readthedocs.io/en/latest/designspaceLib/)

_explanations/documentation.md

@@ -2,7 +2,7 @@
 title     : Documentation overview
 layout    : default
 permalink : /explanations/documentation/
-order     : 901
+order     : 999
 ---
 
 <nav aria-label="breadcrumb">

_explanations/explanations.md

@@ -8,8 +8,9 @@ draft     : true
 Topics at a higher level or even from different perspectives. Explanations can equally well be described as discussions.
 {: .lead }
 
-- [Understanding variable components](understanding-variable-components){% comment %}order: 101{% endcomment %}
-- [Documentation overview](documentation){% comment %}order: 901{% endcomment %}
+- [Designspace](designspace){% comment %}order: 901{% endcomment %}
+- [Understanding variable components](understanding-variable-components){% comment %}order: 902{% endcomment %}
+- [Documentation overview](documentation){% comment %}order: 999{% endcomment %}
 {% comment %}
 - [Why another font editing software?](#)
 - [Why Fontra Pak](#)

_explanations/understanding-variable-components.md

@@ -3,7 +3,7 @@ title     : Understanding variable components
 layout    : default
 permalink : /explanations/understanding-variable-components/
 draft     : true
-order     : 101
+order     : 902
 ---
 
 <nav aria-label="breadcrumb">

_reference/menu.md

@@ -40,7 +40,7 @@ order     : 600
 <td>Includes: Font info, Axes, Sources, Status definitions</td>
 </tr>
 <tr>
-<td>Help</td>
-<td>For example, link to documentation, github, ...</td>
+<td><a href='../menu/help'>Help</a></td>
+<td>For example, link to documentation, github, last changes, ...</td>
 </tr>
 </table>

_reference/menu/font.md

@@ -23,21 +23,26 @@ order     : 640
 </tr>
 <tr>
 <td>1</td>
-<td>Font Info</td>
+<td><a href='{{ site.url }}/reference/menu/font/font-info'>Font Info</a></td>
 <td>Settings about various names, vendor information, UPM, ...</td>
 </tr>
 <tr>
 <td>2</td>
-<td>Axes</td>
-<td>Axes Setting like min max default values, value mappings, ...</td>
+<td><a href='{{ site.url }}/reference/menu/font/axes'>Axes</a></td>
+<td>Axes settings like min max default values, value mappings, ...</td>
 </tr>
 <tr>
 <td>3</td>
-<td>Sources</td>
-<td>Font source settings like name, location, vertical metrics, ...</td>
+<td><a href='{{ site.url }}/reference/menu/font/cross-axis-mapping'>Cross-axis mapping</a></td>
+<td>Cross-axis mapping settings with inout and output locations</td>
 </tr>
 <tr>
 <td>4</td>
+<td><a href='{{ site.url }}/reference/menu/font/sources'>Sources</a></td>
+<td>Font source settings like name, location, vertical metrics, ...</td>
+</tr>
+<tr>
+<td>5</td>
 <td><a href='{{ site.url }}/reference/menu/font/status-colors'>Status Definitions</a></td>
 <td>Status definition settings like color, name, isDefault.</td>
 </tr>

_reference/menu/font/axes.md

@@ -0,0 +1,165 @@
+---
+title     : Axes
+layout    : default
+permalink : /reference/menu/font/axes
+draft     : true
+order     : 642
+---
+
+<nav aria-label="breadcrumb">
+  <ol class="breadcrumb small">
+    <li class="breadcrumb-item"><a href="{{ site.url }}">Index</a></li>
+    <li class="breadcrumb-item"><a href="{{ site.url }}/reference">Reference</a></li>
+    <li class="breadcrumb-item"><a href="{{ site.url }}/reference/menu">Menu</a></li>
+    <li class="breadcrumb-item"><a href="{{ site.url }}/reference/menu/font">Font</a></li>
+    <li class="breadcrumb-item active" aria-current="page">{{ page.title }}</li>
+  </ol>
+</nav>
+
+Fontra's approach is *variable-first*, therefore it's most likey that you will add at least one font axis. The most common one is probably *Weight*. Add a new axis via the *New axis...* button. 
+{: .lead }
+
+<div class="alert alert-primary mt-3" role="alert" markdown='1'>
+#### Pro tips: 
+{: .alert-heading}
+- Before you create a new axis we recommend to have a look at **[Designspace](/explanations/designspace/)**, first.
+- Change the order of the axes via *drag and drop*.
+{: .mb-0 }
+</div>
+
+![]({{ site.url }}/images/font-axes.png){: .img-fluid }
+
+Names
+-------
+
+<table class='table table-hover'>
+<tr>
+<th width='35%'>Entry</th>
+<th width='65%'>Description</th>
+</tr>
+<tr>
+<td>Name<a href="#marker_1">¹</a></td>
+<td>The axis name identifies the axis</td>
+</tr>
+<tr>
+<td>OT tag</td>
+<td>The axis tag <b>must be 4 characters</b> long. <a href='https://learn.microsoft.com/en-us/typography/opentype/spec/dvaraxisreg#registered-axis-tags' target="_blank">Registered OT tags</a>. Non-registered tags must be written in all uppercase.</td>
+</tr>
+<tr>
+<td>UI Name<a href="#marker_1">¹</a></td>
+<td>UI Name is <b>the Label how it will be visible</b> to the end user</td>
+</tr>
+</table>
+
+
+<span id='marker_1'>¹Note: **Name** and **UI Name** are often the same.</span>
+{% comment %}
+For more please see: https://github.com/googlefonts/fontra-docs/pull/77#issuecomment-2518494551
+{% endcomment %}
+
+Range
+-------
+
+<table class='table table-hover'>
+<tr>
+<th width='35%'>Entry</th>
+<th width='65%'>Description</th>
+</tr>
+<tr>
+<td>Axis Type</td>
+<td>Either <b>Continuous<a href="#marker_2">²</a></b> or <b>Discrete<a href="#marker_3">³</a></b></td>
+</tr>
+</table>
+
+<span id='marker_2'>²Range: Axis type *Continuous*</span>
+-------
+
+<table class='table table-hover'>
+<tr>
+<th width='35%'>Entry</th>
+<th width='65%'>Description</th>
+</tr>
+<tr>
+<td>Minimum</td>
+<td>the minimum value of the axis (for example: <b>100 for Thin</b> in a Weight axis)</td>
+</tr>
+<tr>
+<td>Default</td>
+<td>the default value of the axis (for example: <b>400 for Regular</b> in a Weight axis)</td>
+</tr>
+<tr>
+<td>Maximum</td>
+<td>the maximum value of the axis (for example: <b>900 for Black</b> in a Weight axis)</td>
+</tr>
+</table>
+
+<span id='marker_3'>³Range: Axis type *Discrete*</span>
+-------
+
+<table class='table table-hover'>
+<tr>
+<th width='35%'>Entry</th>
+<th width='65%'>Description</th>
+</tr>
+<tr>
+<td>Values</td>
+<td>a list of values for the axis (for example: <b>0 for Upright</b> and <b>1 for Italic</b> for Italic axis)</td>
+</tr>
+<tr>
+<td>Default</td>
+<td>the default value of the axis (for example: <b>0 for Upright</b> in the Italic axis)</td>
+</tr>
+</table>
+
+Mapping graph
+-------
+
+The mapping graph visualizes the axis mapping.
+
+Mapping list
+-------
+
+Specify a new mapping of the axis values (also known as avar-mapping). Add a new mapping with the plus-button or remove a mapping with the minus-button.
+
+
+Axis Values
+-------
+
+Add a new axis value with plus-button or remove it via minus-button (keyword: STAT table).
+
+<table class='table table-hover'>
+<tr>
+<th width='35%'>Entry</th>
+<th width='65%'>Description</th>
+</tr>
+<tr>
+<td>Name</td>
+<td>The name of a specifed style (for example <b>Regular</b>)</td>
+</tr>
+<tr>
+<td>Value</td>
+<td>The value of a style (for example <b>400</b> for Regular)</td>
+</tr>
+<tr>
+<td>Min</td>
+<td>The minumum value of a style (for example <b>350</b> for Regular)</td>
+</tr>
+<tr>
+<td>Max</td>
+<td>The maximum value of a style (for example <b>450</b> for Regular)</td>
+</tr>
+<tr>
+<td>Linked</td>
+<td>The linked value of a style (for example <b>700</b> for Regular, so it's <b>linked with Bold</b>)</td>
+</tr>
+<tr>
+<td>Elidable</td>
+<td>A checkbox which shows that the name should not be displayed (<b>Upright might be an elidable</b> name in the Italic axis)</td>
+</tr>
+</table>
+
+
+
+### Links
+
+- [Google Fonts: Axis (in variable fonts)](https://fonts.google.com/knowledge/glossary/axis_in_variable_fonts)

_reference/menu/font/cross-axis-mapping.md

@@ -0,0 +1,52 @@
+---
+title     : Cross-axis mapping
+layout    : default
+permalink : /reference/menu/font/cross-axis-mapping
+draft     : true
+order     : 644
+---
+
+<nav aria-label="breadcrumb">
+  <ol class="breadcrumb small">
+    <li class="breadcrumb-item"><a href="{{ site.url }}">Index</a></li>
+    <li class="breadcrumb-item"><a href="{{ site.url }}/reference">Reference</a></li>
+    <li class="breadcrumb-item"><a href="{{ site.url }}/reference/menu">Menu</a></li>
+    <li class="breadcrumb-item"><a href="{{ site.url }}/reference/menu/font">Font</a></li>
+    <li class="breadcrumb-item active" aria-current="page">{{ page.title }}</li>
+  </ol>
+</nav>
+
+This panel allows you to add, modify or remove cross-axis mappings (also known as avar2 mappings). Use the *New cross-axis mapping* button for creating a new cross-axis mapping. Every mapping has an input and output location. Not all axes need to participate in a mapping – you can handle this with the checkbox next to an axis. It is most likey that your font project does not need such a cross-axis mapping, therefore only specify a mapping if you know what you do.
+{: .lead }
+
+<div class="alert alert-primary mt-3" role="alert" markdown='1'>
+#### Pro tips: 
+{: .alert-heading}
+- Alt-key + click the arrow: show/hide all card information.
+{: .mb-0 }
+</div>
+
+![]({{ site.url }}/images/font-cross-axis-mapping.png){: .img-fluid }
+
+
+<table class='table table-hover'>
+<tr>
+<th width='35%'>Entry</th>
+<th width='65%'>Description</th>
+</tr>
+<tr>
+<td>Group Description</td>
+<td>optional, string</td>
+</tr>
+<tr>
+<td>Description</td>
+<td>„optional, string. the description of this mappings group“ (Reference: <a href='https://github.com/fonttools/fonttools/blob/main/Doc/source/designspaceLib/xml.rst#mappings-element' target="_blank">mappings-element</a>)</td>
+</tr>
+</table>
+
+
+### Links
+
+- [Proposal for representing avar2 mappings in designspace documents](https://github.com/harfbuzz/boring-expansion-spec/blob/main/avar2-in-designspace.md)
+- [fonttools: mappings-element](https://github.com/fonttools/fonttools/blob/main/Doc/source/designspaceLib/xml.rst#mappings-element)
+- [fonttools: mappings example](https://github.com/fonttools/fonttools/blob/main/Doc/source/designspaceLib/xml.rst#34example-of-all-mappings-elements-together)