Style conventions

[BWibo]

Hey all,

@clausnagel @yaozhihang @SchultzeMax @marina-rug @MScMOSS @thomashkolbe

I just went through some PRs and realized we should agree to some conventions to make sure the we use a consistent style.
Here are some examples where we currently have inconsistencies. Feel free to edit this post to add things you find when reading.

Headlines

There are cases of capitalization in headlines, e.g. Import Options or Cityjson-Specific Import Options.
I suggest we use regular english spelling and do not capitalize things.

Spelling

There are inconsistencies in spellings of some names.

This is the correct spelling:

• CityGML
• CityJSON
• citydb-tool

File paths

File paths and file names should be styled as code. There are some cases where this is not the case.

Code blocks

I found several codeblocks I found hard to read, because they exceeded the width of the block/page. For instance:

citydb export citygml --filter="S_INTERSECTS(Envelope, BBOX(-560.8678155819734, 604.1012795512906, -553.8099297783192, 627.1318523068805))" @options.txt -o=output.gml

I suggest we limit the width of codeblocks to a length that does not require scrolling. This can be done using line continuation. Check out the Docker pages for examples for windows and linux.

Important

Line continuation can be tricky! Make sure to test if the new command can be executed when it's copied from the code box in the rendered docs!

I used this style to provide code boxes for windows and linux:

=== "Linux"

    ``` bash
    docker run --name 3dciytdb -p 5432:5432 -d \
        -e POSTGRES_PASSWORD=<theSecretPassword> \
        -e SRID=<EPSG code> \
        [-e HEIGHT_EPSG=<EPSG code>] \
        [-e SRS_NAME=<mySrsName>] \
        [-e POSTGRES_DB=<database name>] \
        [-e POSTGRES_USER=<username>] \
        [-e POSTGIS_SFCGAL=<true|false|yes|no>] \
    3dcitydb/3dcitydb-pg
    ```

=== "Windows"

    ``` bash
    docker run --name 3dciytdb -p 5432:5432 -d ^
        -e POSTGRES_PASSWORD=<theSecretPassword> ^
        -e SRID=<EPSG code> ^
        [-e HEIGHT_EPSG=<EPSG code>] ^
        [-e SRS_NAME=<mySrsName>] ^
        [-e POSTGRES_DB=<database name>] ^
        [-e POSTGRES_USER=<username>] ^
        [-e POSTGIS_SFCGAL=<true|false|yes|no>] ^
    3dcitydb/3dcitydb-pg
    ```

This will render like this:

Is everybody OK with the conventions I outlined above? Is something missing? Please comment if you would like to have it differently.

[clausnagel]

Spelling:

• "CityDB tool" (or any variant of this) should be citydb-tool