Add new argument order to sort inclusions (#279)

Author: mondeja

README.md

@@ -191,6 +191,32 @@ content to include.
 - <a name="include-markdown_recursive" href="#include-markdown_recursive">#</a>
   **recursive** (_true_): When this option is disabled, included files are not
   processed for recursive includes. Possible values are `true` and `false`.
+- <a name="include-markdown_order" href="#include-markdown_order">#</a>
+  **order** (_'alpha-path'_): Define the order in which multiple files are included
+  when using globs. Possible values are:
+  - A combination of an optional order type and an optional order by separated
+    by a hyphen (`-`), and optionally prefixed by a hyphen (`-`) to indicate
+    ascending order. If an order type or an order by is not specified, the defaults
+    are used. It follows the form:
+    `[-]<order_type>-<order_by>` where:
+    - **Order type**:
+      - `'alpha'` (default): Alphabetical order.
+      - `'natural'`: Natural order, so that e.g. `file2.md` comes before `file10.md`.
+    - **Order by**:
+      - `'path'` (default): Order by full file path.
+      - `'name'`: Order by file name only.
+      - `'extension'`: Order by file extension.
+  - A combination of an optional prefix hyphen to denote ascending order and
+    one of the following values in the form `[-]<value>` where `<value>` is one of:
+    - `'size'`: Order by file size.
+    - `'mtime'`: Order by file modification time.
+    - `'ctime'`: Order by file creation time (or the last metadata change time
+      on Unix systems).
+    - `'atime'`: Order by file last access time.
+  - `'random'`: Random order.
+  - `'system'`: Order provided by the operating system. This is the same as not
+    specifying any order and relying on the default order of the filesystem. This
+    may be different between operating systems, so use it with care.
 - <a name="include-markdown_encoding" href="#include-markdown_encoding">#</a>
   **encoding** (_'utf-8'_): Specify the encoding of the included file.
   If not defined `'utf-8'` will be used.
@@ -249,13 +275,21 @@ content to include.
 {%
     include-markdown "**"
     exclude="./{index,LICENSE}.md"
+    order="name"
 %}
 ```
 
 ```jinja
 {% include-markdown '/escap\'ed/single-quotes/in/file\'/name.md' %}
 ```
 
+```jinja
+{%
+    include-markdown "**"
+    order="-natural-extension"
+%}
+```
+
 <!-- mdpo-disable-next-line -->
 
 #### **`include`**
@@ -282,6 +316,32 @@ Includes the content of a file or a group of files.
 - <a name="include_recursive" href="#include_recursive">#</a>
   **recursive** (_true_): When this option is disabled, included files are not
   processed for recursive includes. Possible values are `true` and `false`.
+- <a name="include_order" href="#include_order">#</a>
+  **order** (_'alpha-path'_): Define the order in which multiple files are included
+  when using globs. Possible values are:
+  - A combination of an optional order type and an optional order by separated
+    by a hyphen (`-`), and optionally prefixed by a hyphen (`-`) to indicate
+    ascending order. If an order type or an order by is not specified, the defaults
+    are used. It follows the form:
+    `[-]<order_type>-<order_by>` where:
+    - **Order type**:
+      - `'alpha'` (default): Alphabetical order.
+      - `'natural'`: Natural order, so that e.g. `file2.md` comes before `file10.md`.
+    - **Order by**:
+      - `'path'` (default): Order by full file path.
+      - `'name'`: Order by file name only.
+      - `'extension'`: Order by file extension.
+  - A combination of an optional prefix hyphen to denote ascending order and
+    one of the following values in the form `[-]<value>` where `<value>` is one of:
+    - `'size'`: Order by file size.
+    - `'mtime'`: Order by file modification time.
+    - `'ctime'`: Order by file creation time (or the last metadata change time
+      on Unix systems).
+    - `'atime'`: Order by file last access time.
+  - `'random'`: Random order.
+  - `'system'`: Order provided by the operating system. This is the same as not
+    specifying any order and relying on the default order of the filesystem. This
+    may be different between operating systems, so use it with care.
 - <a name="include_encoding" href="#include_encoding">#</a>
   **encoding** (_'utf-8'_): Specify the encoding of the included file.
   If not defined `'utf-8'` will be used.
@@ -306,6 +366,7 @@ Includes the content of a file or a group of files.
 {%
     include '**'
     exclude='./*.md'
+    order='random'
 %}
 ```
 

locale/es/README.md

@@ -177,6 +177,35 @@ se encuentran en el contenido a incluir se eliminan. Los valores posibles son
 **recursive** (*true*): Cuando esta opción está deshabilitada, los archivos
 incluidos no son procesados para incluir de forma recursiva. Los valores
 posibles son `true` y `false`.
+- <a name="include-markdown_order" href="#include-markdown_order">#</a> **order**
+(*'alpha-path'*): Define el orden en el que múltiples archivos son incluidos
+al usar globs. Los valores posibles son:
+   - Una combinación de un tipo de orden opcional y un sujeto de ordenación opcional
+separados por un guion (`-`), y opcionalmente precedidos por un guion (`-`)
+para indicar orden ascendente. Si no se especifica un tipo de orden o un sujeto
+de ordenación, se usan los valores por defecto. Sigue la forma:
+`[-]<tipo_de_orden>-<sujeto_de_ordenación>` donde:
+      - **Tipo de orden**:
+         - `'alpha'` (por defecto): Orden alfabético.
+         - `'natural'`: Orden natural, de modo que por ejemplo `file2.md` va antes
+`file10.md`.
+      - **Sujeto de ordenación**:
+         - `'path'` (por defecto): Ordena por la ruta completa del archivo.
+         - `'name'`: Ordena sólo por el nombre del archivo.
+         - `'extension'`: Ordena por la extensión del archivo.
+   - Una combinación de un guion opcional al principio para denotar orden ascendente
+y uno de los siguientes valores en la forma `[-]<valor>` donde `<valor>` es
+uno de los siguientes:
+      - `'size'`: Ordena por el tamaño del archivo.
+      - `'mtime'`: Ordena por la hora de modificación del archivo.
+      - `'ctime'`: Ordena por la hora de creación del archivo (o la última hora de
+cambio de metadatos en sistemas Unix).
+      - `'atime'`: Ordena por la última hora de acceso al archivo.
+   - `'random'`: Orden aleatorio.
+   - `'system'`: Orden proporcionado por el sistema operativo. Esto es lo mismo que
+no especificar ningún orden y confiar en el orden por defecto del sistema de
+archivos. Esto puede ser diferente entre sistemas operativos, así que úsalo con
+precaución.
 - <a name="include-markdown_encoding" href="#include-markdown_encoding">#</a>
 **encoding** (*'utf-8'*): Especifica la codificación del archivo incluído. Si
 no se define, se usará `'utf-8'`.
@@ -237,13 +266,21 @@ especificado. Sólo soporta la sintaxis de encabezado de caracteres de hash
 {%
     include-markdown "**"
     exclude="./{index,LICENSE}.md"
+    order="name"
 %}
 ```
 
 ```jinja
 {% include-markdown '/escap\'ed/single-quotes/in/file\'/name.md' %}
 ```
 
+```jinja
+{%
+    include-markdown "**"
+    order="-natural-extension"
+%}
+```
+
 #### **`include`**
 
 Incluye el contenido de un archivo o un grupo de archivos.
@@ -271,6 +308,35 @@ Los valores posibles son `true` y `false`.
 (*true*): Cuando esta opción está deshabilitada, los archivos incluidos no son
 procesados para incluir de forma recursiva. Los valores posibles son `true` y
 `false`.
+- <a name="include_order" href="#include_order">#</a> **order** (*'alpha-path'*):
+Define el orden en el que múltiples archivos son incluidos al usar globs. Los
+posibles valores son:
+   - Una combinación de un tipo de orden opcional y un sujeto de ordenación opcional
+separados por un guion (`-`), y opcionalmente precedidos por un guion (`-`)
+para indicar orden ascendente. Si no se especifica un tipo de orden o un sujeto
+de ordenación, se usan los valores por defecto. Sigue la forma:
+`[-]<tipo_de_orden>-<sujeto_de_ordenación>` donde:
+      - **Tipo de orden**:
+         - `'alpha'` (por defecto): Orden alfabético.
+         - `'natural'`: Orden natural, de modo que por ejemplo `file2.md` va antes
+`file10.md`.
+      - **Sujeto de ordenación**:
+         - `'path'` (por defecto): Ordena por la ruta completa del archivo.
+         - `'name'`: Ordena sólo por el nombre del archivo.
+         - `'extension'`: Ordena por la extensión del archivo.
+   - Una combinación de un guion opcional al principio para denotar orden ascendente
+y uno de los siguientes valores en la forma `[-]<valor>` donde `<valor>` es
+uno de los siguientes:
+      - `'size'`: Ordena por el tamaño del archivo.
+      - `'mtime'`: Ordena por la hora de modificación del archivo.
+      - `'ctime'`: Ordena por la hora de creación del archivo (o la última hora de
+cambio de metadatos en sistemas Unix).
+      - `'atime'`: Ordena por la última hora de acceso al archivo.
+   - `'random'`: Orden aleatorio.
+   - `'system'`: Orden proporcionado por el sistema operativo. Esto es lo mismo que
+no especificar ningún orden y confiar en el orden por defecto del sistema de
+archivos. Esto puede ser diferente entre sistemas operativos, así que úsalo con
+precaución.
 - <a name="include_encoding" href="#include_encoding">#</a> **encoding**
 (*'utf-8'*): Especifica la codificación del archivo incluído. Si no se define,
 se usará `'utf-8'`.
@@ -295,6 +361,7 @@ se usará `'utf-8'`.
 {%
     include '**'
     exclude='./*.md'
+    order='random'
 %}
 ```
 

locale/es/README.md.po

@@ -471,3 +471,95 @@ msgid ""
 msgstr ""
 "Se agregará un archivo *.gitignore* al directorio de caché si no existe para"
 " evitar confirmar los archivos de caché."
+
+msgid ""
+"<a name=\"include-markdown_order\" href=\"#include-markdown_order\">#</a> "
+"**order** (*'alpha-path'*): Define the order in which multiple files are "
+"included when using globs. Possible values are:"
+msgstr ""
+"<a name=\"include-markdown_order\" href=\"#include-markdown_order\">#</a> "
+"**order** (*'alpha-path'*): Define el orden en el que múltiples archivos son"
+" incluidos al usar globs. Los valores posibles son:"
+
+msgid "**Order type**:"
+msgstr "**Tipo de orden**:"
+
+msgid "`'alpha'` (default): Alphabetical order."
+msgstr "`'alpha'` (por defecto): Orden alfabético."
+
+msgid ""
+"`'natural'`: Natural order, so that e.g. `file2.md` comes before "
+"`file10.md`."
+msgstr ""
+"`'natural'`: Orden natural, de modo que por ejemplo `file2.md` va antes "
+"`file10.md`."
+
+msgid "**Order by**:"
+msgstr "**Sujeto de ordenación**:"
+
+msgid "`'path'` (default): Order by full file path."
+msgstr "`'path'` (por defecto): Ordena por la ruta completa del archivo."
+
+msgid "`'name'`: Order by file name only."
+msgstr "`'name'`: Ordena sólo por el nombre del archivo."
+
+msgid ""
+"A combination of an optional prefix hyphen to denote ascending order and one"
+" of the following values in the form `[-]<value>` where `<value>` is one of:"
+msgstr ""
+"Una combinación de un guion opcional al principio para denotar orden "
+"ascendente y uno de los siguientes valores en la forma `[-]<valor>` donde "
+"`<valor>` es uno de los siguientes:"
+
+msgid "`'size'`: Order by file size."
+msgstr "`'size'`: Ordena por el tamaño del archivo."
+
+msgid "`'mtime'`: Order by file modification time."
+msgstr "`'mtime'`: Ordena por la hora de modificación del archivo."
+
+msgid ""
+"`'ctime'`: Order by file creation time (or the last metadata change time on "
+"Unix systems)."
+msgstr ""
+"`'ctime'`: Ordena por la hora de creación del archivo (o la última hora de "
+"cambio de metadatos en sistemas Unix)."
+
+msgid "`'atime'`: Order by file last access time."
+msgstr "`'atime'`: Ordena por la última hora de acceso al archivo."
+
+msgid "`'random'`: Random order."
+msgstr "`'random'`: Orden aleatorio."
+
+msgid ""
+"`'system'`: Order provided by the operating system. This is the same as not "
+"specifying any order and relying on the default order of the filesystem. "
+"This may be different between operating systems, so use it with care."
+msgstr ""
+"`'system'`: Orden proporcionado por el sistema operativo. Esto es lo mismo "
+"que no especificar ningún orden y confiar en el orden por defecto del "
+"sistema de archivos. Esto puede ser diferente entre sistemas operativos, así"
+" que úsalo con precaución."
+
+msgid ""
+"<a name=\"include_order\" href=\"#include_order\">#</a> **order** (*'alpha-"
+"path'*): Define the order in which multiple files are included when using "
+"globs. Possible values are:"
+msgstr ""
+"<a name=\"include_order\" href=\"#include_order\">#</a> **order** (*'alpha-"
+"path'*): Define el orden en el que múltiples archivos son incluidos al usar "
+"globs. Los posibles valores son:"
+
+msgid "`'extension'`: Order by file extension."
+msgstr "`'extension'`: Ordena por la extensión del archivo."
+
+msgid ""
+"A combination of an optional order type and an optional order by separated "
+"by a hyphen (`-`), and optionally prefixed by a hyphen (`-`) to indicate "
+"ascending order. If an order type or an order by is not specified, the "
+"defaults are used. It follows the form: `[-]<order_type>-<order_by>` where:"
+msgstr ""
+"Una combinación de un tipo de orden opcional y un sujeto de ordenación "
+"opcional separados por un guion (`-`), y opcionalmente precedidos por un "
+"guion (`-`) para indicar orden ascendente. Si no se especifica un tipo de "
+"orden o un sujeto de ordenación, se usan los valores por defecto. Sigue la "
+"forma: `[-]<tipo_de_orden>-<sujeto_de_ordenación>` donde:"

locale/fr/README.md

@@ -178,6 +178,35 @@ trouvées dans le contenu à inclure sont supprimées. Les valeurs possibles son
 **recursive** (*true*): Lorsque cette option est désactivée, les fichiers
 inclus ne sont pas traités pour des inclusions récursives. Les valeurs possibles
 sont `true` et `false`.
+- <a name="include-markdown_order" href="#include-markdown_order">#</a> **order**
+(*'alpha-path'*): Définit l'ordre dans lequel plusieurs fichiers sont inclus
+lors de l'utilisation de globs. Les possibles valeurs sont:
+   - Une combinaison d'un type de commande optionnel et d'un sujet de commande
+optionnel séparés par un trait d'union (`-`), et éventuellement précédés par
+un trait d'union (`-`) pour indiquer l'ordre ascendant. Si un type d'ordre ou un
+sujet d'ordre n'est pas spécifié, les valeurs par défaut sont utilisées. Il suit
+la forme: `[-]<type_d'ordre>-<sujet_d'ordre>` où:
+      - **Type d'ordre**:
+         - `'alpha'` (par défaut): Ordre alphabétique.
+         - `'natural'`: Ordre naturel, de sorte que par exemple `file2.md` vient avant
+`file10.md`.
+      - **Sujet de l'ordre**:
+         - `'path'` (par défaut): Ordre par chemin de fichier complet.
+         - `'name'`: Ordre par nom de fichier uniquement.
+         - `'extension'`: Ordre par extension de fichier.
+   - Une combinaison d'un trait d'union préfixe optionnel pour indiquer l'ordre
+ascendant et l'une des valeurs suivantes sous la forme `[-]<value>` où
+`<value>` est l'une de:
+      - `'size'`: Ordre par taille de fichier.
+      - `'mtime'`: Ordre par heure de modification du fichier.
+      - `'ctime'`: Ordre par heure de création du fichier (ou la dernière heure de
+changement de métadonnées sur les systèmes Unix).
+      - `'atime'`: Ordre par dernière heure d'accès au fichier.
+   - `'random'`: Ordre aléatoire.
+   - `'system'`: Ordre fourni par le système d'exploitation. C'est la même chose que
+de ne spécifier aucun ordre et de se fier à l'ordre par défaut du système de
+fichiers. Cela peut être différent entre les systèmes d'exploitation, alors
+utilisez-le avec précaution.
 - <a name="include-markdown_encoding" href="#include-markdown_encoding">#</a>
 **encoding** (*'utf-8'*): Spécifiez l'encodage du fichier inclus. S'il n'est
 pas défini, `'utf-8'` sera utilisé.
@@ -238,13 +267,21 @@ négatives pour supprimer les caractères `#` de tête.
 {%
     include-markdown "**"
     exclude="./{index,LICENSE}.md"
+    order="name"
 %}
 ```
 
 ```jinja
 {% include-markdown '/escap\'ed/single-quotes/in/file\'/name.md' %}
 ```
 
+```jinja
+{%
+    include-markdown "**"
+    order="-natural-extension"
+%}
+```
+
 #### **`include`**
 
 Inclus le contenu d'un fichier ou d'un groupe de fichiers.
@@ -271,6 +308,35 @@ valeurs possibles sont `true` et `false`.
 (*true*): Lorsque cette option est désactivée, les fichiers inclus ne sont pas
 traités pour des inclusions récursives. Les valeurs possibles sont `true` et
 `false`.
+- <a name="include_order" href="#include_order">#</a> **order** (*'alpha-path'*):
+Définit l'ordre dans lequel plusieurs fichiers sont inclus lors de
+l'utilisation de globs. Les possibles valeurs sont:
+   - Une combinaison d'un type de commande optionnel et d'un sujet de commande
+optionnel séparés par un trait d'union (`-`), et éventuellement précédés par
+un trait d'union (`-`) pour indiquer l'ordre ascendant. Si un type d'ordre ou un
+sujet d'ordre n'est pas spécifié, les valeurs par défaut sont utilisées. Il suit
+la forme: `[-]<type_d'ordre>-<sujet_d'ordre>` où:
+      - **Type d'ordre**:
+         - `'alpha'` (par défaut): Ordre alphabétique.
+         - `'natural'`: Ordre naturel, de sorte que par exemple `file2.md` vient avant
+`file10.md`.
+      - **Sujet de l'ordre**:
+         - `'path'` (par défaut): Ordre par chemin de fichier complet.
+         - `'name'`: Ordre par nom de fichier uniquement.
+         - `'extension'`: Ordre par extension de fichier.
+   - Une combinaison d'un trait d'union préfixe optionnel pour indiquer l'ordre
+ascendant et l'une des valeurs suivantes sous la forme `[-]<value>` où
+`<value>` est l'une de:
+      - `'size'`: Ordre par taille de fichier.
+      - `'mtime'`: Ordre par heure de modification du fichier.
+      - `'ctime'`: Ordre par heure de création du fichier (ou la dernière heure de
+changement de métadonnées sur les systèmes Unix).
+      - `'atime'`: Ordre par dernière heure d'accès au fichier.
+   - `'random'`: Ordre aléatoire.
+   - `'system'`: Ordre fourni par le système d'exploitation. C'est la même chose que
+de ne spécifier aucun ordre et de se fier à l'ordre par défaut du système de
+fichiers. Cela peut être différent entre les systèmes d'exploitation, alors
+utilisez-le avec précaution.
 - <a name="include_encoding" href="#include_encoding">#</a> **encoding**
 (*'utf-8'*): Spécifiez l'encodage du fichier inclus. S'il n'est pas défini,
 `'utf-8'` sera utilisé.
@@ -295,6 +361,7 @@ traités pour des inclusions récursives. Les valeurs possibles sont `true` et
 {%
     include '**'
     exclude='./*.md'
+    order='random'
 %}
 ```