commit e625a1389aae1bb33adadf5633b51c951182afda
parent dd5a46f9a455d86d3ec18b44e5894d64b86c895e
Author: Christophe Coustet <christophe.coustet@meso-star.com>
Date: Wed, 5 Jun 2024 15:24:20 +0200
Translate ascidoc man page city_generator(1) to mdoc
Diffstat:
3 files changed, 176 insertions(+), 135 deletions(-)
diff --git a/Makefile b/Makefile
@@ -96,8 +96,12 @@ src/cg_version.h: config.mk src/cg_version.h.in
################################################################################
man: doc/city_generator2.1 doc/city_generator2-input.5 doc/city_generator2-output.5
-doc/city_generator2.1: doc/city_generator2.1.txt
- $(A2X) $(A2X_FLAGS) $<
+doc/city_generator2.1: doc/city_generator2.1.in
+ sed -e 's/@CG2_ARGS_DEFAULT_VERBOSITY_LEVEL@/$(CG2_ARGS_DEFAULT_VERBOSITY_LEVEL)/' \
+ -e 's/@CG2_ARGS_CHANGE_BINARY_DEFAULT_OPTION@/$(CG2_ARGS_CHANGE_BINARY_DEFAULT_OPTION)/' \
+ -e 's/@CG2_ARGS_STL_NON_DEFAULT_STR@/$(CG2_ARGS_STL_NON_DEFAULT_STR)/' \
+ -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) $<
@@ -105,13 +109,6 @@ doc/city_generator2-input.5: doc/city_generator2-input.5.txt
doc/city_generator2-output.5: doc/city_generator2-output.5.txt
$(A2X) $(A2X_FLAGS) $<
-doc/city_generator2.1.txt: doc/city_generator2.1.txt.in
- sed -e 's/@CG2_ARGS_DEFAULT_VERBOSITY_LEVEL@/$(CG2_ARGS_DEFAULT_VERBOSITY_LEVEL)/' \
- -e 's/@CG2_ARGS_CHANGE_BINARY_DEFAULT_OPTION@/$(CG2_ARGS_CHANGE_BINARY_DEFAULT_OPTION)/' \
- -e 's/@CG2_ARGS_STL_NON_DEFAULT_STR@/$(CG2_ARGS_STL_NON_DEFAULT_STR)/' \
- -e 's/@CG2_ARGS_STL_DEFAULT_STR@/$(CG2_ARGS_STL_DEFAULT_STR)/' \
- $@.in > $@
-
################################################################################
# Installation
################################################################################
diff --git a/doc/city_generator2.1.in b/doc/city_generator2.1.in
@@ -0,0 +1,170 @@
+.\" 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 5, 2024
+.Dt CITY_GENERATOR2 1
+.Os Linux
+.Sh NAME
+.Nm city_generator2
+.Nd generation of conformal 3D meshes of a city from a simple ascii description
+.Sh SYNOPSIS
+.Nm
+.Op Fl @CG2_ARGS_CHANGE_BINARY_DEFAULT_OPTION@Ehksv
+.Op Fl c Ar file_name
+.Op Fl f Ar building_name
+.Op Fl F Ar level
+.Op Fl m Ar file_name
+.Op Fl V Ar level
+.Sh DESCRIPTION
+.Nm
+generates a city as 3D conformal meshes from an ascii description.
+The description includes the city map and at least one catalog file.
+The provided description must comply with the
+.Xr city_generator2-input 5
+input format.
+.Pp
+The output of
+.Nm
+is a set of STL files, either in ascii or in binary format, that contain the
+various meshes of the ground layers and building parts, along with all their
+boundaries.
+As expected for use by most solvers, including
+.Xr stardis 1
+, the output meshes are conformal.
+The various output files for buildings are named after the name of the building
+they are part of, as well as the name of the part they mesh.
+Please refer to
+.Xr city_generator2-output 5
+for the complete description of this naming scheme.
+.Pp
+.Nm Ns '
+internals rely on the star-cad library which itself relies on the gmsh library.
+.Pp
+The options are as follows:
+.Bl -tag -width Ds
+.It Fl @CG2_ARGS_CHANGE_BINARY_DEFAULT_OPTION@
+Change the output format of the generated STL files to
+@CG2_ARGS_STL_NON_DEFAULT_STR@ (default @CG2_ARGS_STL_DEFAULT_STR@).
+.It Fl c Ar file_name
+Read a catalog file which is a text file in yaml 1.1 format containing datasets
+for a given construction mode. All the datasets in a given file share the
+same construction mode. If the city map uses more than one construction mode,
+the different datasets must be provided in (at least) as many catalog files
+as there are construction modes involved.
+Please refer to
+.Xr city_generator2-input 5
+for more information on formats.
+.It Fl f Ar building_name
+Dump the footprint of the building with the given name, if any.
+Can be used more than once.
+.It Fl F Ar level
+Dump the footprint of some buildings, depending on
+.Ar level . Possible values are:
+.Bl -tag -width Ds
+.It Cm 1
+Dump the footprint of any building not generated due to an error,
+.It Cm 2
+Dump the footprint of any building.
+.El
+.It Fl E
+Don't use escape characters in output text.
+Use as first option to avoid escape characters in initial messages.
+.It Fl h
+Output short help and exit.
+.It Fl k
+Keep running on errors.
+.It Fl m Ar file_name
+Read a city map file which is a text file in yaml 1.1 format containing the
+description of the ground and a list of buildings. The description of an
+individual building includes its footprint and construction mode among other
+things.
+Please refer to
+.Xr city_generator2-input 5
+for more information on formats.
+.It Fl s
+Force single threaded execution. By default use as many threads as available.
+Note however that only some parts of the processing is parallelized.
+Therefore, poor speedup when run multithreaded is not a bug and can even be expected.
+.It Fl v
+Output version information and exit.
+.It Fl V Ar level
+Set the verbosity
+.Ar level
+. Possible values are:
+.Bl -tag -width Ds
+.It Cm 0
+No message,
+.It Cm 1
+Error messages only,
+.It Cm 2
+Error and warning messages,
+.It Cm 3
+Error, warning and informative messages.
+.El
+All the messages are written to standard error.
+Default verbosity
+.Ar level
+is @CG2_ARGS_DEFAULT_VERBOSITY_LEVEL@.
+.El
+.Sh EXIT STATUS
+.Ex -std
+.Sh EXAMPLES
+Generates the city described in the
+.Pa city.yaml
+file, looking for the needed datasets in the
+.Pa catalog0.yaml
+and
+.Pa catalog1.yaml
+datafile:
+.Pp
+.Dl city_generator2 -m city.yaml -c catalog0.yaml -c catalog1.yaml
+.Pp
+.Sh SEE ALSO
+.Xr city_generator2-input 5 ,
+.Xr city_generator2-output 5
+.Rs
+.%A C. Geuzaine and J.-F. Remacle.
+.%T Gmsh: a three-dimensional finite element mesh generator with\
+.built-in pre- and post-processing facilities.
+.%J International Journal for Numerical Methods in Engineering
+.%V 79
+.%N 11
+.%P 1309-1331
+.%D 2009
+.Re
+.Sh STANDARDS
+.Rs
+.%T The StL Format: Standard Data Format for Fabbers
+.%A Marshall Burns
+.%D 1993
+.%U https://www.fabbers.com/tech/STL_Format
+.Re
+.Pp
+.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
+.Li Readynov
+funding program of the Occitanie / Pyrénées-Méditerranée region.
diff --git a/doc/city_generator2.1.txt.in b/doc/city_generator2.1.txt.in
@@ -1,126 +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/>.
-
-:toc:
-
-city_generator2(1)
-==================
-
-NAME
-----
-city_generator2 - generation of conformal 3D meshes of a city from a simple
-ascii description.
-
-SYNOPSIS
---------
-[verse]
-*city_generator2* *-h* [_option_]
-*city_generator2* *-m* <__file__> {*-c* <__file__>}+ [_option_]
-
-DESCRIPTION
------------
-*city_generator2* generates a city as 3D conformal meshes from an ascii
-description. The description includes the city map (a description of the ground
-and buildings in a yaml file), and at least one catalog file (a description of
-a set of datasets grouped by construction modes). The provided description must
-comply with the *city_generator2-input*(5) format.
-
-The output of *city_generator2* is a set of *STL* files, either in ascii or in
-binary format, that contain the various meshes of the ground layers and
-building parts, along with all their boundaries. As expected for use by most
-solvers, including *stardis*(1), the output meshes are conformal.
-The various output files for buildings are named after the name of the building
-they are part of, as well as the name of the part they mesh.
-Please refer to *city_generator2-output*(5) for the complete description of
-this naming scheme.
-
-The internals of *city_generator2* rely on the star-cad library[1] which itself
-relies on the gmsh library[2].
-
-[1] https://gitlab.com/meso-star/star-cad/
-
-[2] C. Geuzaine and J.-F. Remacle. Gmsh: a three-dimensional finite element
-mesh generator with built-in pre- and post-processing facilities.
-International Journal for Numerical Methods in Engineering 79(11),
-pp. 1309-1331, 2009.
-
-MANDATORY OPTIONS
------------------
-*-m* _file_::
- Read a city map file which is a text file in yaml 1.1 format containing the
- description of the ground and a list of buildings. The description of an
- individual building includes its footprint and construction mode among other
- things.
- Please refer to *city_generator2-input*(5) for more information on formats.
-
-*-c* _file_::
- Read a catalog file which is a text file in yaml 1.1 format containing datasets
- for a given construction mode. All the datasets in a given file share the
- same construction mode. If the city map uses more than one construction mode,
- the different datasets must be provided in (at least) as many catalog files
- as there are construction modes involved.
- Please refer to *city_generator2-input*(5) for more information on formats.
-
-OTHER OPTIONS
--------------
-*-@CG2_ARGS_CHANGE_BINARY_DEFAULT_OPTION@*::
- Change the output format of the generated *STL* files to
- @CG2_ARGS_STL_NON_DEFAULT_STR@ (default @CG2_ARGS_STL_DEFAULT_STR@).
-
-*-h*::
- Output short help and exit.
-
-*-s*::
- Force single threaded execution. By default use as many threads as available.
-+
-Note however that only some parts of the processing is parallelized.
-Therefore, poor speedup is not a bug and can even be expected.
-
-*-v*::
- Output version information and exit.
-
-*-V* _level_::
- Set the verbosity level. Possible values are *0* (no message), *1* (error
- messages only), *2* (error and warning messages), and *3* (error, warning
- and informative messages). All the messages are written to _standard error_.
- Default verbosity *level* is @CG2_ARGS_DEFAULT_VERBOSITY_LEVEL@.
-
-EXAMPLES
---------
-Generates the city described in the *city.yaml* file, looking for the needed
-datasets in the *catalog0.yaml* and *catalog1.yaml* datafile:
-
- $ city_generator2 -m city.yaml -c catalog0.yaml -c catalog1.yaml
-
-COPYRIGHT
----------
-Copyright © 2022-2023 Université de Pau et des Pays de l'Adour UPPA,
- CNRS,
- Sorbonne Université,
- Université Paul Sabatier,
- |Meso|Star>.
-
-License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>.
-This is free software. You are free to change and redistribute it. There is NO
-WARRANTY, to the extent permitted by law.
-
-SEE ALSO
---------
-*city_generator2-input*(5),
-*city_generator2-output*(5)
