Fixed issues in docs

Author: bkryza

docs/class_diagrams.md

@@ -90,8 +90,10 @@ type of relationship generated in the class diagrams.
 
 
 By default, a member from which a relationship has been added to the diagram
-between 2 classes will also be rendered inside the class. This behaviour can be
-however disabled by adding the following option to the diagram definition:
+between 2 classes will also be rendered inside as a property inside the class
+box. This behaviour can be however disabled by adding the following option to
+the diagram definition:
+
 ```yaml
 include_relations_also_as_members: false
 ```
@@ -158,7 +160,7 @@ which results in the following diagram:
 ![t00036_class](test_cases/t00036_class.svg)
 
 ### Directory packages
-In case the code base is structured based on subdirectory instead of namespaces
+In case the code base is structured based on subdirectories instead of namespaces
 (or this is a C project, where namespaces are not available), packages can be
 generated based on the location of a given declaration in the filesystem tree,
 by adding also the following option:
@@ -175,8 +177,10 @@ which results in the following diagram:
 > properly configured for your project, if necessary add `relative_to` option to
 > denote the root path against which all relative paths in the config file are
 > calculated.
+
 
 ### Module packages
+
 Finally, to generate UML packages in the diagram based on C++20 modules, use
 the following option:
 
@@ -213,7 +217,7 @@ this can be easily achieved using `context` inclusion filter:
 ```
 
 By default, the diagram will include only elements in direct relationship to
-`ns1::MyClass`, but an addition option called `radius` can be added to this
+`ns1::MyClass`, but an additional option called `radius` can be added to this
 filter, which will extend the context to elements related to `ns1::MyClass`
 through at most N relationships, e.g:
 

docs/common_options.md

@@ -15,30 +15,34 @@
 <!-- tocstop -->
 
 ## Overall configuration file structure
-By default, `clang-uml` will look for file `.clang-uml` in the project's directory and read all diagrams definitions
-configuration from it. The file must be specified in YAML and it's overall structure is as follows:
+By default, `clang-uml` will look for file `.clang-uml` in the project's
+directory and read all diagram definitions configuration from it. The file must
+be specified in YAML and it's overall structure is as follows:
 
 ```yaml
-# common options for all diagrams
-...
+# Common options for all diagrams
+# ...
+# Diagram definitions
 diagrams:
   first_diagram_name:
     type: class|sequence|package|include
-    # diagram specific options
-    ...
+    # Diagram specific options
+    # ...
   second_diagram_name:
     type: class|sequence|package|include
-    # diagram specific options
-    ...
-  ...
+    # Diagram specific options
+    # ...
+  # More diagrams
+  # ...
 ```
 
-The top level common options are inherited by specific diagrams, if the option is applicable to them and they themselves
-do not override this option.
+The top level common options are inherited by specific diagrams, if the option
+is applicable to them and they themselves do not override this option.
 
 For detailed reference of all configuration options see [here](./configuration_file.md).
 
-Effective configuration, including default values can be printed out in YAML format using the following option:
+Effective configuration, including default values can be printed out in YAML
+format using the following option:
 
 ```bash
 clang-uml --dump-config
@@ -56,24 +60,29 @@ diagrams:
 ```
 
 ## Translation unit glob patterns
-One of the key options of the diagram configuration is the list of translation units, which should be parsed to
-get all necessary information for a diagram. 
+One of the key options of the diagram configuration is the list of translation
+units, which should be parsed to get all necessary information for a diagram. 
 
-The syntax is simple and based on glob patterns, which can be added to the configuration file as follows:
+The syntax is simple and based on glob patterns, which can be added to the
+configuration file as follows:
 
 ```yaml
    glob:
      - src/dir1/*.cc
      - src/dir3/*.cc
 ```
 
-The glob patterns only need to match the translation units, which are also in the `compile_commands.json` file, i.e.
-any files that match the glob patterns, but are not in `compile_commands.json` will be ignored. In case the `glob`
-pattern set does not match any translation units an error will be printed on the standard output.
+The glob patterns only need to match the translation units, which are also in
+the `compile_commands.json` file, i.e. any files that match the glob patterns,
+but are not in `compile_commands.json` will be ignored. In case the `glob`
+pattern set does not match any translation units an error will be printed on
+the standard output.
 
-For small projects, the `glob` property can be omitted, which will result in `clang-uml` parsing all translation units
-from `compile_commands.json` for the diagram. However, for large projects, constraining the number of translation units
-for each diagram to absolute minimum will significantly decrease the diagram generation times.
+For small projects, the `glob` property can be omitted, which will result in
+`clang-uml` parsing all translation units from `compile_commands.json` for
+the diagram. However, for large projects, constraining the number of translation
+units for each diagram to minimum necessary to discover all necessary diagram
+elements will significantly decrease the diagram generation times.
 
 ## Custom directives
 In case it's necessary to add some custom PlantUML or MermaidJS declarations
@@ -122,13 +131,13 @@ the generated PlantUML diagram will contain comments before each line containing
 the source location of the specific diagram element.
 
 ## Resolving include path and compiler flags issues
-Due to the fact, that your project can be compiled with different compilers
+Due to the fact, that a project can be compiled with different compilers
 and toolchains, the system paths and compilation flags detected by the Clang
 version linked to your `clang-uml` installation might differ from the ones
 actually used to compile your project.
 
 > This is often an issue on macOS, when `clang-uml` uses Homebrew version of LLVM
-> and your project was built using system Apple Clang
+> and a project was built using system Apple Clang.
 
 Typically, this results in error messages on the console during diagram
 generation, such as:

docs/diagram_filters.md

@@ -40,7 +40,7 @@ to your diagram configuration:
 ```
 
 Some filters accept either specified exact values, some support regular
-expressions while some except glob patterns.
+expressions while some accept glob patterns.
 
 For filters which accept regular expressions, the regular expression has to
 be provided as a map ```r: 'pattern'``` due to the fact the pointer (```*```) otherwise
@@ -54,8 +54,6 @@ exclude:
     - r: '.*test.*'
 ```
 
-`paths` filter is currently the only filter which accepts `glob` like patterns.
-
 The following table specifies the values allowed in each filter:
 
 | Filter name       | Possible values                   | Example values                                                                                                                                          |
@@ -64,7 +62,7 @@ The following table specifies the values allowed in each filter:
 | `modules`         | Qualified name or regex           | ```mod1.mod2:par1```, ```r: '.*impl.*'```                                                                                                               |
 | `elements`        | Qualified name or regex           | ```ns1::ns2::ClassA```, ```r: '.*detail.*'```                                                                                                           |
 | `element_types`   | Types of diagram elements         | ```class```, ```enum```, ```concept```                                                                                                                  |
-| `paths`           | File or dir path or glob pattern  | ```src/dir1```, ```src/dir2/a.cpp```, ```src/dir3/*.cpp```                                                                                              |
+| `paths`           | File or dir path                  | ```src/dir1```, ```src/dir2/a.cpp```, ```src/dir3/*.cpp```                                                                                              |
 | `context`         | Qualified name or regex           | ```ns1::ns2::ClassA```, ```r: 'ns1::ns2::ClassA.+'```                                                                                                   |
 | `relationships`   | Type of relationship              | ```inheritance```, ```composition```, ```aggregation```, ```ownership```, ```association```, ```instantiation```, ```friendship```, ```dependency```    |
 | `subclasses`      | Qualified name or regex           | ```ns1::ns2::ClassA```, ```r: 'ns1::ns2::ClassA.+'```                                                                                                   |

docs/generator_types.md

@@ -51,6 +51,20 @@ instance:
     cmd: "/usr/bin/plantuml -tsvg \"diagrams/{}.puml\""
 ```
 
+Furthermore, `plantuml` generator accepts basic styling options for customizing
+diagram look and layout, e.g.:
+```yaml
+  plantuml:
+    style:
+      # Apply this style to all classes in the diagram
+      class: "#aliceblue;line:blue;line.dotted;text:blue"
+      # Apply this style to all packages in the diagram
+      package: "#back:grey"
+      # Make all template instantiation relations point upwards and draw them
+      # as green and dotted lines
+      instantiation: "up[#green,dotted]"
+```
+
 An example PlantUML diagram is presented below:
 
 ```plantuml
@@ -121,9 +135,9 @@ example:
       - 'note for {{ alias("config") }} "General options not used by diagrams."'
 ```
 
-will add before the diagram contents (right after diagram type,
-e.g. `classDiagram`) diagram direction hint, and after each diagram contents
-2 notes attached to elements.
+will add a diagram direction hint before the diagram contents (right after
+diagram type, e.g. `classDiagram`), and after each diagram contents
+2 notes attached to classes `inheritable_diagram_options` and `config`.
 
 This generator also accepts a `cmd` parameter to specify a command to execute
 on the generated MermaidJS source file to generate actual diagram image, for

docs/include_diagrams.md

@@ -56,5 +56,5 @@ source files (matched by `glob`) and not their dependencies, for example:
 ![t40001_include](./test_cases/t40001_include.svg)
 
 Please note that generating include diagram, which contains third party and
-system library headers will result in a huge diagram that will be unlikely to
+system library headers will result in a huge diagram that is unlikely to
 be useful.

docs/installation.md

@@ -23,7 +23,7 @@
 #### Ubuntu
 
 ```bash
-# Currently supported Ubuntu versions are Focal, Jammy, Lunar and Mantic
+# Currently supported Ubuntu versions are Focal, Jammy and Mantic
 sudo add-apt-repository ppa:bkryza/clang-uml
 sudo apt update
 sudo apt install clang-uml
@@ -33,16 +33,16 @@ sudo apt install clang-uml
 
 ```bash
 # Fedora 37
-wget https://github.com/bkryza/clang-uml/releases/download/0.4.2/clang-uml-0.4.2-1.fc37.x86_64.rpm
-sudo dnf install ./clang-uml-0.4.2-1.fc37.x86_64.rpm
+wget https://github.com/bkryza/clang-uml/releases/download/0.5.1/clang-uml-0.5.1-1.fc37.x86_64.rpm
+sudo dnf install ./clang-uml-0.5.1-1.fc37.x86_64.rpm
 
 # Fedora 38
-wget https://github.com/bkryza/clang-uml/releases/download/0.4.2/clang-uml-0.4.2-1.fc38.x86_64.rpm
-sudo dnf install ./clang-uml-0.4.2-1.fc38.x86_64.rpm
+wget https://github.com/bkryza/clang-uml/releases/download/0.5.1/clang-uml-0.5.1-1.fc38.x86_64.rpm
+sudo dnf install ./clang-uml-0.5.1-1.fc38.x86_64.rpm
 
 # Fedora 39
-wget https://github.com/bkryza/clang-uml/releases/download/0.4.2/clang-uml-0.4.2-1.fc39.x86_64.rpm
-sudo dnf install ./clang-uml-0.4.2-1.fc39.x86_64.rpm
+wget https://github.com/bkryza/clang-uml/releases/download/0.5.1/clang-uml-0.5.1-1.fc39.x86_64.rpm
+sudo dnf install ./clang-uml-0.5.1-1.fc39.x86_64.rpm
 ```
 
 #### Conda
@@ -79,7 +79,7 @@ release/src/clang-uml --help
 
 # To build using a specific installed version of LLVM use:
 LLVM_VERSION=16 make release
-# or specify path to a specific llvm-config binary, e.g.:
+# or specify a path to a specific llvm-config binary, e.g.:
 LLVM_CONFIG_PATH=/usr/bin/llvm-config-16 make release
 # or directly specify the path where LLVMConfig.cmake can be found on your system, e.g.:
 CMAKE_PREFIX=/usr/lib/llvm-16/lib/cmake/llvm make release
@@ -111,7 +111,7 @@ CMAKE_PREFIX=/usr/local/opt/llvm/lib/cmake/llvm make release
 
 ##### Visual Studio native build
 
-These steps present how to build and use `clang-uml` natively using Visual Studio only.
+These steps present how to build and use `clang-uml` natively using Microsoft Visual Studio only.
 
 First, install the following dependencies manually:
 

docs/package_diagrams.md

@@ -7,8 +7,8 @@
 <!-- tocstop -->
 
 Package diagrams are simple diagrams, which can be useful to visualize a high
-level structure of a C++ project, by rendering project's namespaces or
-subdirectories as UML packages and their interdependencies.
+level structure of a C++ project, by rendering project's namespaces,
+subdirectories or modules as UML packages and their interdependencies.
 
 The minimal config required to generate a package diagram is presented below:
 ```yaml
@@ -163,7 +163,8 @@ the configuration file:
 package_type: directory
 ```
 
-for example check out this diagram
+for example check out this diagram (you can click on package names to see the 
+corresponding source directory):
 ![t30011_package](./test_cases/t30011_package.svg)
 
 Module based packages can be enabled using the following option:
@@ -172,8 +173,9 @@ Module based packages can be enabled using the following option:
 package_type: module
 ```
 
-for example check out this diagram
-![t30014_package](./test_cases/t30011_package.svg)
+for example check out this diagram (you can click on package names to see the
+corresponding module source):
+![t30014_package](./test_cases/t30012_package.svg)
 
 Diagrams can be rendered relative to a specific module using `using_module`
 option:

docs/quick_start.md

@@ -52,9 +52,9 @@ To add an initial class diagram to your project, follow these steps:
    mmdc -i diagrams/some_class_diagram.mmd -o diagrams/some_class_diagram.svg
    ```
    
-   Steps 3 and 4 can be combined into one step like follows:
+   Steps 3 and 4 can be combined into one step:
    ```
-   clang-uml -p -n some_class_diagram -g plantuml -r --plantuml-cmd="plantuml -tsvg diagrams/{}.puml"
+   clang-uml -p -n some_class_diagram -g plantuml -r --plantuml-cmd="/usr/bin/plantuml -tsvg diagrams/{}.puml"
    ```
    where `-r` enables diagram rendering and `--plantuml-cmd` specifies command
    to execute on each generated diagram.

docs/sequence_diagrams.md

@@ -74,7 +74,7 @@ there are 3 types of constraints:
               locations
 
 Currently, the constraints can be a method or a free function, both specified
-using the full signature of the function, e.g.
+using the full signature of the function, e.g.:
 
 ```yaml
     from:
@@ -97,8 +97,8 @@ and `to` locations as follows:
          function: "clanguml::t20034::A::a2()"]
 ```
 
-To find the exact function signature which, can be used as a `from` location,
-run `clang-uml` as follows:
+To find the exact function signature, which can be used as a `from` location,
+run `clang-uml` as follows (assuming the function of interest is called `main`):
 
 ```bash
 clang-uml --print-from -n main_sequence | grep main
@@ -112,7 +112,7 @@ clang-uml --print-to -n main_sequence | grep main
 
 Command line flags `--print-from` and `--print-to` will print on stdout all
 functions and methods available in the diagram model, and each line of this
-output can be directly used as a value of `start_from`, `from_to` or `to`
+output can be directly used as a value of `from`, `from_to` or `to`
 properties in the config file.
 
 Since that list can be quite large, it's best to filter the output to limit
@@ -141,7 +141,7 @@ tentative support, which follows the following rules:
   * If lambda expression is passed to some function or method, which is outside
     the scope of the diagram (e.g. used in `std::transform` call) the call will
     not be generated
-  * If the lambda is passed as template parameter in instantiation it will not
+  * If the lambda is passed as template argument in instantiation it will not
     be generated
 
 Another issue is the naming of lambda participants. Currently, each lambda is
@@ -257,7 +257,7 @@ The default participant order in the sequence diagram can be suboptimal in the
 sense that consecutive calls can go right, then left, then right again
 depending on the specific call chain in the code. It is however possible to
 override this order in the diagram definition using `participants_order`
-property, for instance like this test case:
+property, for instance like this:
 
 ```yaml
 diagrams:
@@ -372,5 +372,5 @@ for each sequence diagram, which should include these comments.
 
 In case only selected messages should have some specific comments, instead
 of enabling the `generate_message_comments` option, it is possible to use
-`\uml{note TEXT}` directive in the comment above the expression, see
+`\\uml{note TEXT}` directive in the comment above the expression, see
 [t20001](test_cases/t20001_sequence.svg).

docs/troubleshooting.md

@@ -22,7 +22,7 @@
 
 ## General issues
 
-### clang-uml crashes when generating diagram
+### clang-uml crashes when generating a diagram
 
 If `clang-uml` crashes with a segmentation fault, it is possible to trace the
 exact stack trace of the fault using the following steps:
@@ -346,7 +346,7 @@ the exact string representation of the function signature as seen by `clang-uml`
 To find the exact function signature run `clang-uml` as follows:
 
 ```bash
-clang-uml -n my_sequence_diagram --print-start-from | grep foo
+clang-uml -n my_sequence_diagram --print-from | grep foo
 ```
 
 Command line flag `--print-from` will print on stdout all functions