Factorio talk:Style guide: Difference between revisions

From Official Factorio Wiki
Jump to navigation Jump to search
mNo edit summary
No edit summary
 
(2 intermediate revisions by 2 users not shown)
Line 17: Line 17:
Are either of these appropriate? If so which one? Is there another way that would work better to the style and legibility of the wiki?
Are either of these appropriate? If so which one? Is there another way that would work better to the style and legibility of the wiki?
--[[User:Soundfoam|Soundfoam]] ([[User talk:Soundfoam|talk]]) 7:49, 29 October 2024 (UTC)
--[[User:Soundfoam|Soundfoam]] ([[User talk:Soundfoam|talk]]) 7:49, 29 October 2024 (UTC)
: The quality effects should be noted in the row of the property they affect, so for example directly in the health row. So like in your first image. You can find documentation on the infoboxes, including how to do the quality, on [[Template:Infobox]]. -- [[User:Bilka|Bilka]] ([[User talk:Bilka|talk]]) - <span style="color:#FF0000">Admin</span> 15:17, 1 November 2024 (UTC)
{{clear}}
== Draft: equation style guide ==
This is not a guide on proper LaTeX syntax within the math environment, such a guide can be found here: [https://www.mediawiki.org/wiki/Extension:Math/Syntax Extension:Math/Syntax].
Unfortunately, the more specific the styles are the more difficult they are to be implemented by a laymen not familiar with LaTeX.
However, LaTeX already is a hurdle of entry, and it doesn't have a very wide usecase except more niche places on the wiki like the Tutorial namespace.
<div style="
    margin: 15px;
    padding: 5px 10px;
    border-radius: 0;
    background: #242324;
    border-color: #141414 #3E3E3E #3E3E3E #141414;
    border-style: solid;
    border-width: 3px;">
=== Preferred Notation ===
* '''Multiplication''': In multiplication of scalar values <code><nowiki>\cdot</nowiki></code> is preferred over <code><nowiki>\times</nowiki></code>. However, <code><nowiki>*</nowiki></code> may not be used.
* '''Division''': Divisions must be handled as fractions <code><nowiki>\frac{...}{...}</nowiki></code>. The <code><nowiki>\div</nowiki></code> operator may not be used.
* '''Differential d''': The differential d must be non-italicized as <code><nowiki><math>\mathrm{d}</math></nowiki></code>.
* '''Function names'''A number of functions already exist in the math environment like <code><nowiki><math>\sin \log \exp \ln</math></nowiki></code> resulting in <math>\sin \log \exp \ln</math>. If an editor wants to use other functions like the binary logarithm (logarithmus dualis) they can use <code><nowiki>\mathrm{...}</nowiki></code> to revert the italics to write <code><nowiki><math>\log_2 = \mathrm{ld}</math></nowiki></code> resulting in <math>\log_2 = \mathrm{ld}</math>.
* '''Function arguments''': Parentheses around function arguments are must be used <code><nowiki><math>\sin (\alpha)</math></nowiki></code> <math>\sin (\alpha)</math>, they may not be omitted.
* '''Time derivatives''': Dot notation may be used for time derivatives, like <code><nowiki><math>\dot{m} := \tfrac{\mathrm{d}m}{\mathrm{d}t}</math></nowiki></code> <math>\dot{m} := \tfrac{\mathrm{d}m}{\mathrm{d}t}</math>
===Units ===
* '''Units should not be italicized''', but symbols in equations are italicized by default, therefore the exceptions must be treated by wrapping them in <code><nowiki>\mathrm{...}</nowiki></code>. And between the quantity and the unit should be a small gap, which can be done in the math environment with a <code><nowiki>\,</nowiki></code>
: Example: <code><nowiki><math>t = 15 \, \mathrm{s}</math></nowiki></code> results in <math>t = 15 \, \mathrm{s}</math>
* '''Compound of multiple units''': the different units should also be separated by a small gap. If a unit is fractional, it should use text style fractions <code><nowiki>\tfrac{...}{...}</nowiki></code>, especially for inline equations.
: Example 1: Energy usage in kilowatt-hours: <code><nowiki><math>E = 720 \, \mathrm{kW}\, \mathrm{h}</math></nowiki></code> results in <math>E = 720 \, \mathrm{kW}\, \mathrm{h}</math>
: Example 2: Resource flow in units per minute: <code><nowiki><math>\dot{m} = 750 \, \tfrac{\mathrm{u}}{\mathrm{min}}</math> science</nowiki></code> results in <math>\dot{m} = 750 \, \tfrac{\mathrm{u}}{\mathrm{min}}</math> science
<!---
*** Incorrect: <code><nowiki><math>t = 15 \mathrm{s}</math></nowiki></code> <math>t = 15 \mathrm{s}</math>
*** Incorrect: <code><nowiki><math>t = 15 \, s</math></nowiki></code> <math>t = 15 \, s</math>
*** Incorrect: <code><nowiki><math>t = 15s</math></nowiki></code> <math>t = 15s</math>
*** Incorrect: units per minute: <code><nowiki><math>750\frac{\mathrm{u}}{\mathrm{min}}</math> science</nowiki></code> <math>750\frac{\mathrm{u}}{\mathrm{min}}</math> science
-->
=== Separators ===
* '''Symbol separator''': Symbols separated by no operator are implied to get multiplied together. However, as one symbol can consist of multiple glyphs, they should be separated by a small gap. A small gap can be done in the math environment with a <code><nowiki>\,</nowiki></code>.
: Example: <code><nowiki><math>\Delta F = k \, \Delta x</math></nowiki></code> <math>\Delta F = k \, \Delta x</math>
* '''Quantity seperator''': When symbols are replaced by the quantity and unit they represent, a operator must be given.
: Example: <code><nowiki><math>10 \, \mathrm{N} = 50 \, \tfrac{\mathrm{N}}{\mathrm{m}} \cdot 0.2 \, \mathrm{N}</math></nowiki></code> <math>10 \, \mathrm{N} = 50 \, \tfrac{\mathrm{N}}{\mathrm{m}} \cdot 0.2 \, \mathrm{N}</math>
* '''Thousands separator''': To aid the eye, but be non-intrusive or confusing, the thousands separator should be a small gap, not a comma or period. This should also apply to every thousandth after the decimal place.
: Example: <code><nowiki><math>12 \, \mathrm{MJ} = 12\,000\,000 \, \mathrm{J}</math></nowiki></code> <math>12 \, \mathrm{MJ} = 12\,000\,000 \, \mathrm{J}</math>
<!--** Incorrect: <code><nowiki><math>12 \, \mathrm{MJ} = 12 000 000 \, \mathrm{J}</math></nowiki></code> <math>12 \, \mathrm{MJ} = 12 000 000 \, \mathrm{J}</math>
** Incorrect: <code><nowiki><math>12 \, \mathrm{MJ} = 12.000.000 \, \mathrm{J}</math></nowiki></code> <math>12 \, \mathrm{MJ} = 12.000.000 \, \mathrm{J}</math>
** Incorrect: <code><nowiki><math>12 \, \mathrm{MJ} = 12,000,000 \, \mathrm{J}</math></nowiki></code> <math>12 \, \mathrm{MJ} = 12,000,000 \, \mathrm{J}</math>
-->
* '''Decimal separator''': The decimal separator is a period in America and most English-speaking countries, but a comma in Europe and most Arabic-speaking countries. As the wiki is in English, the decimal separator should also be period.
: Example: <code><nowiki><math>\pi = 3.141\,592\,653\,589</math></nowiki></code> <math>\pi = 3.141\,592\,653\,589</math>
<!--** Incorrect: <code><nowiki><math>\pi = 3,141\,592\,653\,589</math></nowiki></code> <math>\pi = 3,141\,592\,653\,589</math>
-->
=== Large equations ===
Equations that will span multiple lines should be placed in their own paragraphs. Then they should be properly aligned in either an <code>align</code> or <code>array</code> environment
<div style="display:flex; flex-wrap: wrap; column-gap: 1em;">
<div>
<pre>
<math>
\begin{align}
E &= \int_{t_0}^{t_1} P(t) \, \mathrm{d}t \qquad P(t) \approx P_\mbox{peak}\\
  &= \int_{t_0}^{t_1} P_\mbox{peak} \, \mathrm{d}t\\
  &= P_\mbox{peak} \, \int_{t_0}^{t_1} \, \mathrm{d}t\\
  &= P_\mbox{peak} \, (t_1 - t_0)\\
\end{align}
</math>
</pre>
</div><div>
<math>
\begin{align}
E &= \int_{t_0}^{t_1} P(t) \, \mathrm{d}t \qquad P(t) \approx P_\mbox{peak}\\
  &= \int_{t_0}^{t_1} P_\mbox{peak} \, \mathrm{d}t\\
  &= P_\mbox{peak} \, \int_{t_0}^{t_1} \, \mathrm{d}t\\
  &= P_\mbox{peak} \, (t_1 - t_0)\\
\end{align}
</math>
</div>
</div>
</div>

Latest revision as of 15:13, 8 November 2024

How can I add a blueprint?

I would like to edit https://wiki.factorio.com/Tutorial:Combinator_tutorial#Memory, and I would like to add blueprints to make it easier to follow along. I would very much appreciate some guidance on the preferred way of sharing blueprints here on the Wiki. --Ndh (talk) 17:30, 27 June 2024 (UTC)

Hey, you interest is appreciated! You can use Template:BlueprintString for blueprint strings, see Inserters#Inserter_Throughput for example. Tutorial:Circuit_network_cookbook#Memory_Cell_/_Counter may also interest you. Happy editing! -- Bilka (talk) - Admin 17:50, 27 June 2024 (UTC)
Ooooh that is awesome! Thank you so much! Although now I'm wondering how I could have found this. On the left there is a list of links under "Editor Help", but "Templates" links to some generic mediawiki page. Would it be possible maybe to change this link to https://wiki.factorio.com/Category:Templates instead? Both https://wiki.factorio.com/Special:WhatLinksHere/Category:Templates and https://wiki.factorio.com/Special:WhatLinksHere/Category:Documentation_templates are pretty empty right now. Or maybe the style guide would be the better place? --Ndh (talk) 18:02, 27 June 2024 (UTC)
Usually people find the templates by seeing them used on the wiki. But that doesn't refute your point, so I linked to the category in the style guide section about templates. -- Bilka (talk) - Admin 15:05, 30 August 2024 (UTC)

Adding 'Quality' to Non-Space-Age Pages

I was editing the page for the Solar panel infobox to include quality information, but I wanted to check if there was a certain way we wanted to do this. Either adding it directly to the boxes quality affects, like the first image attached:

Solarpanelquality-editor question.png

Or if we should use the quality infobox template and list the items changed, like the second image attatched:

Solarpanelquality-editor question2.png

Are either of these appropriate? If so which one? Is there another way that would work better to the style and legibility of the wiki? --Soundfoam (talk) 7:49, 29 October 2024 (UTC)

The quality effects should be noted in the row of the property they affect, so for example directly in the health row. So like in your first image. You can find documentation on the infoboxes, including how to do the quality, on Template:Infobox. -- Bilka (talk) - Admin 15:17, 1 November 2024 (UTC)

Draft: equation style guide

This is not a guide on proper LaTeX syntax within the math environment, such a guide can be found here: Extension:Math/Syntax.

Unfortunately, the more specific the styles are the more difficult they are to be implemented by a laymen not familiar with LaTeX. However, LaTeX already is a hurdle of entry, and it doesn't have a very wide usecase except more niche places on the wiki like the Tutorial namespace.

Preferred Notation

  • Multiplication: In multiplication of scalar values \cdot is preferred over \times. However, * may not be used.
  • Division: Divisions must be handled as fractions \frac{...}{...}. The \div operator may not be used.
  • Differential d: The differential d must be non-italicized as <math>\mathrm{d}</math>.
  • Function namesA number of functions already exist in the math environment like <math>\sin \log \exp \ln</math> resulting in . If an editor wants to use other functions like the binary logarithm (logarithmus dualis) they can use \mathrm{...} to revert the italics to write <math>\log_2 = \mathrm{ld}</math> resulting in .
  • Function arguments: Parentheses around function arguments are must be used <math>\sin (\alpha)</math> , they may not be omitted.
  • Time derivatives: Dot notation may be used for time derivatives, like <math>\dot{m} := \tfrac{\mathrm{d}m}{\mathrm{d}t}</math>

Units

  • Units should not be italicized, but symbols in equations are italicized by default, therefore the exceptions must be treated by wrapping them in \mathrm{...}. And between the quantity and the unit should be a small gap, which can be done in the math environment with a \,
Example: <math>t = 15 \, \mathrm{s}</math> results in
  • Compound of multiple units: the different units should also be separated by a small gap. If a unit is fractional, it should use text style fractions \tfrac{...}{...}, especially for inline equations.
Example 1: Energy usage in kilowatt-hours: <math>E = 720 \, \mathrm{kW}\, \mathrm{h}</math> results in
Example 2: Resource flow in units per minute: <math>\dot{m} = 750 \, \tfrac{\mathrm{u}}{\mathrm{min}}</math> science results in science

Separators

  • Symbol separator: Symbols separated by no operator are implied to get multiplied together. However, as one symbol can consist of multiple glyphs, they should be separated by a small gap. A small gap can be done in the math environment with a \,.
Example: <math>\Delta F = k \, \Delta x</math>
  • Quantity seperator: When symbols are replaced by the quantity and unit they represent, a operator must be given.
Example: <math>10 \, \mathrm{N} = 50 \, \tfrac{\mathrm{N}}{\mathrm{m}} \cdot 0.2 \, \mathrm{N}</math>
  • Thousands separator: To aid the eye, but be non-intrusive or confusing, the thousands separator should be a small gap, not a comma or period. This should also apply to every thousandth after the decimal place.
Example: <math>12 \, \mathrm{MJ} = 12\,000\,000 \, \mathrm{J}</math>
  • Decimal separator: The decimal separator is a period in America and most English-speaking countries, but a comma in Europe and most Arabic-speaking countries. As the wiki is in English, the decimal separator should also be period.
Example: <math>\pi = 3.141\,592\,653\,589</math>

Large equations

Equations that will span multiple lines should be placed in their own paragraphs. Then they should be properly aligned in either an align or array environment

<math>
\begin{align}
E &= \int_{t_0}^{t_1} P(t) \, \mathrm{d}t \qquad P(t) \approx P_\mbox{peak}\\
  &= \int_{t_0}^{t_1} P_\mbox{peak} \, \mathrm{d}t\\
  &= P_\mbox{peak} \, \int_{t_0}^{t_1} \, \mathrm{d}t\\
  &= P_\mbox{peak} \, (t_1 - t_0)\\
\end{align}
</math>