commit c4298196eee9f26155534a950b777d1dda070134
parent a6ade286b862f74420b4bd841e8f9b446bd157df
Author: Christophe Coustet <christophe.coustet@meso-star.com>
Date: Fri, 7 Jun 2024 17:12:56 +0200
Translate ascidoc man page city_generator-input(5) to mdoc
Diffstat:
3 files changed, 160 insertions(+), 190 deletions(-)
diff --git a/Makefile b/Makefile
@@ -103,9 +103,6 @@ doc/city_generator2.1: doc/city_generator2.1.in
-e 's/@CG2_ARGS_STL_DEFAULT_STR@/$(CG2_ARGS_STL_DEFAULT_STR)/' \
$@.in > $@
-doc/city_generator2-input.5: doc/city_generator2-input.5.txt
- $(A2X) $(A2X_FLAGS) $<
-
doc/city_generator2-output.5: doc/city_generator2-output.5.txt
$(A2X) $(A2X_FLAGS) $<
diff --git a/doc/city_generator2-input.5 b/doc/city_generator2-input.5
@@ -0,0 +1,160 @@
+.\" Copyright (C) 2022-2023 Université de Pau et des Pays de l'Adour UPPA
+.\" Copyright (C) 2022-2023 CNRS
+.\" Copyright (C) 2022-2023 Sorbonne Université
+.\" Copyright (C) 2022-2023 Université Paul Sabatier
+.\" Copyright (C) 2022-2023 |Meso|Star>.
+.\"
+.\" This program is free software: you can redistribute it and/or modify
+.\" it under the terms of the GNU General Public License as published by
+.\" the Free Software Foundation, either version 3 of the License, or
+.\" (at your option) any later version.
+.\"
+.\" This program is distributed in the hope that it will be useful,
+.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+.\" GNU General Public License for more details.
+.\"
+.\" You should have received a copy of the GNU General Public License
+.\" along with this program. If not, see <http://www.gnu.org/licenses/>.
+.Dd June 7, 2024
+.Dt CITY_GENERATOR2-INTPUT 5
+.Os
+.Sh NAME
+.Nm city_generator2-input
+.Nd description of input file formats for
+.Xr city_generator2 1
+.Sh DESCRIPTION
+.Nm
+are the formats used by the
+.Xr city_generator2 1
+program to describe a city.
+They all rely on the yaml 1.1 syntax.
+.Xr 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.
+.Pp
+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.
+.Pp
+Note however that yaml syntax admits multiple equivalent expressions.
+Thus, the rules given thereafter could have been written differently.
+Experienced yaml users can use any equivalent syntax instead of the one
+introduced here.
+.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.\" Grammar in Backus-Naur form
+.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.Sh GRAMMAR
+.Ss 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.
+.Pp
+The city map file format is as follows:
+.Bl -column (descr-line) (::) ()
+.It Ao Va city-map-file Ac Ta ::= Ta Ao Va ground-desc Ac
+.It Ta Ta Ao Va building-list Ac
+.It Ao Va ground-desc Ac Ta ::= Ta Qo ground: Qc
+.It Ta Ta Qo \ \ extend: \& Qc Ao Va extend Ac
+.It Ta Ta Qo \ \ depth: \& Qc Ao Va depth Ac
+.It Ao Va building-list Ac Ta ::= Ta Qo buildings: Qc
+.It Ta Ta Ao Va buildings Ac
+.It Ao Va extent Ac Ta ::= Ta Qo \&[ Qc Ao Va Xmin Ac Qo , Qc\
+ Ao Va Ymin Ac Qo , Qc Ao Va Xsize Ac Qo , Qc Ao Va Ysize Ac Qo ] Qc
+.It Ao Va depth Ac Ta ::= Ta Vt REAL No # > 0, in m
+.It Ao Va buildings Ac Ta ::= Ta Ao Va building Ac
+.It Ta Ta [ \& Ao Va buildings Ac \& ]
+.It Ao Va Xmin Ac Ta ::= Ta Vt REAL No # in m
+.It Ao Va Ymin Ac Ta ::= Ta Vt REAL No # in m
+.It Ao Va Xsize Ac Ta ::= Ta Vt REAL No # > 0, in m
+.It Ao Va Ysize Ac Ta ::= Ta Vt REAL No # > 0, in m
+.It Ao Va building Ac Ta ::= Ta Qo \ \ -name: \& Qc Ao Va name Ac
+.It Ta Ta Qo \ \ \ construction_mode: \& Qc Ao Va cmode-name Ac
+.It Ta Ta Qo \ \ \ dataset: \& Qc Ao Va dataset-name Ac
+.It Ta Ta Qo \ \ \ height: \& Qc Ao Va height Ac
+.It Ta Ta Qo \ \ \ footprint: [ Qc Ao Va vertices Ac Qo ] Qc
+.It Ao Va name Ac Ta ::= Ta Vt STRING
+.It Ao Va cmode-name Ac Ta ::= Ta Qo Construction_Mode_0 Qc | Qo Construction_Mode_1 Qc
+.It Ao Va dataset-name Ac Ta ::= Ta Vt STRING
+.It Ta Ta # The name must be found in a catalog file
+.It Ta Ta # with the same construction mode
+.It Ao Va height Ac Ta ::= Ta Vt REAL No # > 0, in m
+.It Ao Va vertices Ac Ta ::= Ta Ao Va vertex Ac Bo \& Qo , Qc Ao Va vertices Ac \& Bc
+.It Ta Ta # \&At least 3 vertices
+.It Ao Va vertex Ac Ta ::= Ta Qo \&[ Qc Ao Va X Ac Qo , Qc Ao Va Y Ac Qo ] Qc
+.It Ao Va X Ac Ta ::= Ta Vt REAL No # in m
+.It Ao Va Y Ac Ta ::= Ta Vt REAL No # in m
+.El
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.Ss CATALOG FILE FORMAT
+There are currently two different catalog file formats, identified by name,
+and the way
+.Xr city_generator2 1
+is designed allows for additional catalog formats to be implemented.
+.Pp
+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.
+.Pp
+The catalog file format is as follows:
+.Bl -column (descri-line) (::) ()
+.It Ao Va catalog-file Ac Ta ::= Ta Ao Va catalog-file-0 Ac | Ao Va catalog-file-1 Ac
+.It Ao Va catalog-file-0 Ac Ta ::= Ta Qo construction_mode: Construction_Mode_0 Qc
+.It Ta Ta Qo datasets: \& Qc
+.It Ta Ta Ao Va datasets-0 Ac
+.It Ao Va catalog-file-1 Ac Ta ::= Ta Qo construction_mode: Construction_Mode_1 Qc
+.It Ta Ta Qo datasets: \& Qc
+.It Ta Ta Ao Va datasets-1 Ac
+.It Ao Va datasets-0 Ac Ta ::= Ta Ao Va dataset-0 Ac
+.It Ta Ta [ \& Ao Va datasets-0 Ac \& ]
+.It Ao Va datasets-1 Ac Ta ::= Ta Ao Va dataset-1 Ac
+.It Ta Ta [ \& Ao Va datasets-1 Ac \& ]
+.It Ao Va dataset-0 Ac Ta ::= Ta Qo \ \ -name: \& Qc Ao Va name Ac
+.It Ta Ta Qo \ \ \ wall_thickness: \& Qc Vt REAL No # > 0, in m
+.It Ta Ta Qo \ \ \ floor_thickness: \& Qc Vt REAL No # > 0, in m
+.It Ao Va dataset-1 Ac Ta ::= Ta Qo \ \ -name: \& Qc Ao Va name Ac
+.It Ta Ta Qo \ \ \ wall_thickness: \& Qc Vt REAL No # > 0, in m
+.It Ta Ta Qo \ \ \ floor_thickness: \& Qc Vt REAL No # > 0, in m
+.It Ta Ta Qo \ \ \ inter_floor_count: \& Qc Vt INTEGER No # >= 0
+.It Ta Ta Qo \ \ \ inter_floor_thickness: \& Qc Vt REAL No # > 0, in m
+.It Ta Ta Qo \ \ \ roof_thickness: \& Qc Vt REAL No # > 0, in m
+.It Ta Ta Qo \ \ \ crawl_height: \& Qc Vt REAL No # >= 0, in m
+.It Ta Ta Qo \ \ \ attic_height: \& Qc Vt REAL No # >= 0, in m
+.It Ta Ta Qo \ \ \ glass_ratio: \& Qc Vt REAL No # >= 0 and <= 1
+.It Ta Ta Qo \ \ \ floor_insulation_thickness: \& Qc Vt REAL
+.It Ta Ta No # >= 0, in m
+.It Ta Ta Qo \ \ \ roof_insulation_thickness: \& Qc Vt REAL
+.It Ta Ta No # >= 0, in m
+.It Ta Ta Qo \ \ \ internal_insulation_thickness: \& Qc Vt REAL
+.It Ta Ta No # >= 0, in m
+.It Ta Ta Qo \ \ \ external_insulation_thickness: \& Qc Vt REAL
+.It Ta Ta No # >= 0, in m
+.It Ta Ta Qo \ \ \ foundation_depth: \& Qc Vt REAL No # >= 0, in m
+.It Ao Va name Ac Ta ::= Ta Vt STRING
+.El
+.Sh SEE ALSO
+.Xr city_generator2 1
+.Sh STANDARDS
+.Rs
+.%T YAML Ain't Markup Language version 1.1
+.%A Oren Ben-Kiki
+.%A Clark Evans
+.%A Ingy döt Net
+.%D 2005
+.%U https://yaml.org/spec/1.1
+.Re
+.Sh HISTORY
+.Nm
+has been initially developed as part of the
+.Sy Readynov
+.No funding program of the Occitanie / Pyrénées-Méditerranée region.
diff --git a/doc/city_generator2-input.5.txt b/doc/city_generator2-input.5.txt
@@ -1,187 +0,0 @@
-// Copyright (C) 2022-2023 Université de Pau et des Pays de l'Adour UPPA
-// Copyright (C) 2022-2023 CNRS
-// Copyright (C) 2022-2023 Sorbonne Université
-// Copyright (C) 2022-2023 Université Paul Sabatier
-// Copyright (C) 2022-2023 |Meso|Star>.
-//
-// This program is free software: you can redistribute it and/or modify
-// it under the terms of the GNU General Public License as published by
-// the Free Software Foundation, either version 3 of the License, or
-// (at your option) any later version.
-//
-// This program is distributed in the hope that it will be useful,
-// but WITHOUT ANY WARRANTY; without even the implied warranty of
-// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
-// GNU General Public License for more details.
-//
-// 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}
-
-:toc:
-
-= city_generator2-input(5)
-
-== NAME
-
-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.
-
-Note however that yaml syntax admits multiple equivalent expressions. Thus, the
-rules given thereafter could have been written differently. Experienced yaml
-users can use any equivalent syntax instead of the one introduced here.
-
-[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)
-
--------------------------------------
-
-<buildings> ::= " -name: " <name>
- " construction_mode: " <cmode-name>
- " dataset: " <dataset-name>
- " height: " <height>
- " footprint: [" <vertices> "]"
-
-<name> ::= STRING
-
-<cmode-name> ::= "Construction_Mode_0" | "Construction_Mode_1"
-
-<dataset-name> ::= STRING # The name must be found in a catalog file
- # with the same construction mode
-
-<height> ::= <REAL> # in ]0, INF)
-
-<vertices> ::= <vertex> [ "," <vertices> ] # At least 3 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>
- "datasets:"
- <datasets-0>
-
-<catalog-file-1> ::= <construction-mode-1>
- "datasets:"
- <datasets-1>
-
--------------------------------------
-
-<construction-mode-0> ::= "construction_mode: Construction_Mode_0"
-
-<construction-mode-1> ::= "construction_mode: 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
-
-*city_generator2*(1)
