docs: document bsputil

bsputil/bsputil.cc

@@ -138,6 +138,7 @@ static void ReplaceTexturesFromWad(mbsp_t &bsp)
 
 static void PrintModelInfo(const mbsp_t *bsp)
 {
+    // TODO: remove, bspinfo .json export is more useful
     for (size_t i = 0; i < bsp->dmodels.size(); i++) {
         const dmodelh2_t *dmodel = &bsp->dmodels[i];
         logging::print("model {:3}: {:5} faces (firstface = {})\n", i, dmodel->numfaces, dmodel->firstface);
@@ -702,8 +703,8 @@ int bsputil_main(int argc, char **argv)
     fmt::print("---- bsputil / ericw-tools {} ----\n", ERICWTOOLS_VERSION);
     if (argc == 1) {
         printf(
-            "usage: bsputil [--replace-entities] [--extract-entities] [--extract-textures] [--replace-textures f]\n"
-            "[--convert bsp29|bsp2|bsp2rmq|q2bsp] [--check] [--modelinfo]\n"
+            "usage: bsputil [--scale x y z] [--replace-entities] [--extract-entities] [--extract-textures] [--replace-textures f]\n"
+            "[--convert bsp29|bsp2|bsp2rmq|hexen2|hexen2bsp2|hexen2bsp2rmq|hl|q2bsp|qbism] [--check] [--modelinfo]\n"
             "[--check] [--compare otherbsp] [--findfaces x y z nx ny nz] [--findleaf x y z] [--settexinfo facenum texinfonum]\n"
             "[--decompile] [--decompile-geomonly] [--decompile-hull n]\n"
             "[--extract-bspx-lump lump_name output_file_name]\n"
@@ -1067,6 +1068,7 @@ int bsputil_main(int argc, char **argv)
                 }
             }
         } else if (!strcmp(argv[i], "--compare")) {
+            // TODO: remove, this was an early attempt at a testing framework before our current one
             i++;
             if (i == argc - 1) {
                 Error("--compare requires two arguments");

docs/bsputil.rst

@@ -12,34 +12,128 @@ Synopsis
 Description
 ===========
 
-**bsputil is a small utility for basic manipulation of Quake BSP
-files.**
+bsputil is a small utility for in-place manipulation of Quake BSP
+files.
 
 Options
 =======
 
 .. program:: bsputil
 
-.. option:: --extract-textures
+.. option:: --scale x y z
 
-   Extract the texture data from *BSPFILE*\ **and create a Quake WAD**
-   file. The output filename is generated from *BSPFILE*\ **by**
-   stripping the .bsp extension and adding the .wad extension.
+   Scale the .bsp by the given scale factors.
+
+   This is experimental, only a few entity properties are edited:
+
+   - ``origin``
+   - ``lip``
+   - ``height``
+
+.. option:: --replace-entities ENTFILE
+
+   Replaces the .bsp's entity lump with the contents of ENTFILE.
+
+   .. todo::
+
+      Apparently this can handle being BSPFILE being a path to a .MAP file,
+      and update one map file given the entities in a second, ENTFILE.
+
+      Move this functionality to :doc:`maputil`?
+
+.. option:: --convert FORMAT
+
+   Convert the input .bsp to one of the given formats:
+
+   - bsp29
+   - bsp2
+   - bsp2rmq
+   - hexen2
+   - hexen2bsp2
+   - hexen2bsp2rmq
+   - hl
+   - q2bsp
+   - qbism
+
+   This is a "container" conversion only, so most conversions will not be
+   usable.
 
 .. option:: --extract-entities
 
-   Extract the entity data from *BSPFILE*\ **and create a plain** text
+   Extract the entity data from *BSPFILE* and create a plain text
    .ent file. The output filename is generated from *BSPFILE* by
    stripping the .bsp extension and adding the .ent extension.
 
+.. option:: --extract-textures
+
+   Extract the texture data from *BSPFILE* and create a Quake WAD
+   file. The output filename is generated from *BSPFILE* by
+   stripping the .bsp extension and adding the .wad extension.
+
+.. option:: --replace-textures WADFILE
+
+   Replace any textures in *BSPFILE* with updated versions from *WADFILE*.
+
+   .. note::
+
+      A warning will be issued if any texture sizes don't match between
+      *BSPFILE* and *WADFILE*.
+
 .. option:: --check
    
-   Load *BSPFILE*\ **into memory and run a set of tests to check that**
+   Load *BSPFILE* into memory and run a set of tests to check that
    all internal data structures are self-consistent. Currently the tests
    are very basic and not all warnings will result in errors from all
    versions of the Quake engine. This option is not targeted at level
-   designers, but is intended to assist with development of the **qbsp
-   tool and check that a "clean" bsp file is generated.**
+   designers, but is intended to assist with development of the qbsp
+   tool and check that a "clean" bsp file is generated.
+
+.. option:: --modelinfo
+
+   Print some information on all models in the .bsp.
+
+   .. todo:: Deprecated in favour of the .json export of :doc:`bspinfo`.
+
+.. option:: --findfaces x y z nx ny nz
+
+   Find faces with the given x, y, z coordinates inside the face, and
+   the face having the given normal nx, ny, nz.
+
+.. option:: --findleaf x y z
+
+   Prints the leaf at the given coordinates.
+
+.. option:: --settexinfo facenum texinfonum
+
+   Change the texinfo of a given face.
+
+.. option:: --decompile
+
+   Decompile *BSPFILE* to ``BSPFILE.decompile.map``.
+
+.. option:: --decompile-geomonly
+
+   Decompile *BSPFILE* to ``BSPFILE.decompile.map`` without texturing.
+
+.. option:: --decompile-ignore-brushes
+
+   Decompile *BSPFILE* to ``BSPFILE.decompile.map`` without using the Q2 brushes lump.
+
+.. option:: --decompile-hull N
+
+   Decompile only the given hull number to ``BSPFILE.decompile.hullN.map``
+
+.. option:: --extract-bspx-lump LUMPNAME OUTFILENAME
+
+   Write the BSPX lump *LUMPNAME* to *OUTFILENAME*.
+
+.. option:: --insert-bspx-lump LUMPNAME INFILENAME
+
+   Read *INFILENAME* and insert it as a BSPX lump *LUMPNAME* in *BSPFILE*.
+
+.. option:: --remove-bspx-lump LUMPNAME
+
+   Removes *LUMPNAME* from *BSPFILE*.
 
 Author
 ======