commit de769d36c252d971b4892920bf5554769f4cd835
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, 158 insertions(+), 12 deletions(-)
diff --git a/doc/city_generator2-input.5.txt b/doc/city_generator2-input.5.txt
@@ -17,22 +17,168 @@
// 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 input file 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 next two sections describe their formats.
+
+Because these files are yaml files, they must comply with yaml syntax rules,
+including the hard part that is spacing. The following grammar rules that begin
+with a verbatim text must all start at column 1. From here, the amount of
+whitespace characters in verbatim text must be strictly observed. Also, text
+appearing between quote marks has to be used verbatim in the input, 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.
+
+[1] https://yaml.org/
+
+=== CITY MAP FILE FORMAT
+
+The city map file aims to describe the ground, that is currently limited to a
+single layer, with a depth, and the list of buildings on the ground. Each
+building is described in the same way, regardless of its construction mode, that
+is part of the description.
+
+==== GRAMMAR
+
+[verse]
+_______
+<city-map-file> ::= <ground-description>
+ <building-list>
+
+<ground-description> ::= "ground:"
+ " extent: " <extent>
+ " depth: " <depth>
+
+<building-list> ::= "building: "
+ <buildings>
+
+-------------------------------------
+
+<extent> ::= "[ <Xmin> "," <Ymin> "," <Xsize> "," <Ysize> ]
+
+<depth> ::= <REAL> # in ]0, INF)
+
+<Xmin> ::= <REAL>
+
+<Ymin> ::= <REAL>
+
+<buildings> ::= <building>
+ [ <buildings> ]
+
+<Xsize> ::= <REAL> # in ]0, INF)
+
+<Ysize> ::= <REAL> # in ]0, INF)
+
+-------------------------------------
+
+<building> ::= " -id: " <name>
+ " model: " <cmode-name>
+ " data: " <dataset-name>
+ " height: " <height>
+ " polygon: [" <vertices> "]" # At least 3 vertices
+
+<name> ::= STRING
+
+<cmode-name> ::= "construction_Mode_0" | "construction_Mode_1"
+
+<dataset-name> ::= STRING
+
+<height> ::= <REAL> # in ]0, INF)
+
+<vertices> ::= <vertex> [ "," <vertices> ]
+
+-------------------------------------
+
+<vertex> ::= "[" <X> "," <Y> "]"
+
+<X> ::= <REAL>
+
+<Y> ::= <REAL>
+
+______________
+
+=== CATALOG FILE FORMATS
+
+There are currently two different catalog file formats, identified by name, and
+the way city-generator2 is designed allows for additional catalog formats to be
+implemented.
+
+All catalog files contain the name of the construction mode to which they add
+datasets, and a list of datasets. What differs between catalog file formats is
+the format of the datasets. It is obviously expected that datasets use the
+format associated with the named construction mode.
+
+==== GRAMMAR
+
+[verse]
+_______
+<catalog-file> ::= <catalog-file_0 > | <catalog-file_1>
+
+<catalog-file-0> ::= <construction-mode-0>
+ "sets:"
+ <datasets-0>
+
+<catalog-file-1> ::= <construction-mode-1>
+ "sets:"
+ <datasets-1>
+
+-------------------------------------
+
+<construction-mode-0> ::= "construction_mode_type: construction_Mode_0"
+
+<construction-mode-1> ::= "construction_mode_type: construction_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)
