commit f7b403795a2cab2c97f198c9654ad0a28a3e55a4
parent 58956b86b55b42de5e7e72c48beb79a4234c0b58
Author: Christophe Coustet <christophe.coustet@meso-star.com>
Date: Fri, 13 Jan 2023 18:10:21 +0100
Add man pages for input files
Diffstat:
1 file changed, 97 insertions(+), 12 deletions(-)
diff --git a/doc/city_generator2-input.5.txt b/doc/city_generator2-input.5.txt
@@ -17,22 +17,107 @@
// You should have received a copy of the GNU General Public License
// along with this program. If not, see <http://www.gnu.org/licenses/>.
-:sharp: #
+:sharp: {sharp}
:toc:
-city_generator2-input(5)
-========================
+= city_generator2-input(5)
-NAME
-----
-city_generator2-input - city description for city_generator2(1)
+== NAME
-DESCRIPTION
------------
-*city_generator2-input* is the format used by the *city_generator2*(1) program
-to describe a city. It relies on the yaml 1.1 syntax.
+city_generator2-input - description of the input files formats for
+city_generator2(1)
+
+== DESCRIPTION
+
+*city_generator2-input*(5) are the formats used by the *city_generator2*(1)
+program to describe a city. They all rely on the yaml 1.1 syntax[1].
+*city_generator2*(1) reads two different types of files: a single map file, and
+at least one catalog file. The followig two sections describe their formats.
+
+[1] https://yaml.org/
+
+=== CITY MAP FILE FORMAT
+
+b
+
+=== CATALOG FILE FORMATS
+
+There are currently two different catalog file formats, identified by name, and
+the way city-generator is designed allows for additional catalog formats to be
+implemented.
+
+All catalog files contain the name of the constructive mode they add datasets
+to, and a list of datasets. What differs among catalog file formats is the
+format of the datasets. It is obviously expected that datasets use the format
+associated with the named constructive mode.
+
+==== GRAMMAR
+
+Catalog files being yaml files, they must comply with yaml syntax rules,
+including the hard part that is spacing. The following grammar rules that start
+with a verbatim item are all expected to start at column 1. From there, the
+amount of whitespace characters in verbatim items must be strictly observed.
+Also, text appearing between quote marks has to be used verbatim in the input,
+with or without the quote characters. Finally, text introduced by the *#*
+character in descriptions, when not verbatim, is a comment and is not part of
+the description.
+
+[verse]
+_______
+<catalog-file> ::= <catalog-file_0 > | <catalog-file_1>
+
+<catalog-file-0> ::= <constructive-mode-0>
+ "sets:"
+ <datasets-0>
+
+<catalog-file-1> ::= <constructive-mode-1>
+ "sets:"
+ <datasets-1>
+
+-------------------------------------
+
+<constructive-mode-0> ::= "constructive_mode_type: Constructive_Mode_0"
+
+<constructive-mode-1> ::= "constructive_mode_type: Constructive_Mode_1"
+
+-------------------------------------
+
+<datasets_0> ::= <dataset_0>
+ [ <datasets_0> ]
+
+<datasets_1> ::= <dataset_1>
+ [ <datasets_1> ]
+
+-------------------------------------
+
+<dataset_0> ::= " - name: " <name>
+ " wall_thickness: " <REAL> {sharp} in ]0, INF)
+ " floor_thickness: " <REAL> {sharp} in ]0, INF)
+
+<dataset_1> ::= " - name: " <name>
+ " inter_floor_count: " <REAL> {sharp} in ]0, INF)
+ " wall_thickness: " <REAL> {sharp} in ]0, INF)
+ " floor_thickness: " <REAL> {sharp} in ]0, INF)
+ " inter_floor_thickness: " <REAL> {sharp} in ]0, INF)
+ " roof_thickness: " <REAL> {sharp} in ]0, INF)
+ " internal_insulation_thickness: " <REAL> {sharp} in ]0, INF)
+ " external_insulation_thickness: " <REAL> {sharp} in ]0, INF)
+ " floor_insulation_thickness: " <REAL> {sharp} in ]0, INF)
+ " roof_insulation_thickness: " <REAL> {sharp} in ]0, INF)
+ " foundation_depth: " <REAL> {sharp} in ]0, INF)
+ " crawl_height: " <REAL> {sharp} in ]0, INF)
+ " attic_height: " <REAL> {sharp} in ]0, INF)
+ " glass_ratio: " <REAL> {sharp} in ]0, INF)
+
+-------------------------------------
+
+<name> ::= STRING
+
+______________
+
+
+== SEE ALSO
+:w
-SEE ALSO
---------
*city_generator2*(1)
