From 3b7e6e61ec31e1e18bc623875242e972e71e6c5f Mon Sep 17 00:00:00 2001 From: tmorin Date: Sat, 5 Dec 2020 09:47:08 +0100 Subject: [PATCH] fix(documentation): rephrase part of the library documentation --- README.md | 11 +++++------ dist/README.md | 31 +++++++++++++++++-------------- lib/glib/template/library.md | 31 +++++++++++++++++-------------- 3 files changed, 39 insertions(+), 34 deletions(-) diff --git a/README.md b/README.md index 4c1a234cc98..c07e386d85f 100644 --- a/README.md +++ b/README.md @@ -15,7 +15,7 @@ This repository hosts a [PlantUML] lib which provides several `packages`. Each package focus on a particular technology/approach: Amazon Web Services (AWS), Azure, C4 Model or even EventStorming and more. The repository hosts also two command lines utilities. -The first one (`glib`) helps to generate packages, the second one (`gdiag`) helps to use the packages within external projects in order to bootstrap a local and generate diagrams. +The first one (`glib`) helps to generate packages, the second one (`gdiag`) helps to use the packages from external projects in order. ## Contributing @@ -42,7 +42,7 @@ The available packages: ## Usage -The library can directly be used remotely hitting the GitHub repository. +The library can be directly used remotely hitting the GitHub repository. However, the performances are not good enough for intensive usage. In this case, the library should be installed locally and use directly from the file system. @@ -51,11 +51,10 @@ To help the local installation, an NPM package is available. ## Usage of the NPM package -A npm package [@tmorin/plantuml-libs](https://www.npmjs.com/package/@tmorin/plantuml-libs) is available. -Its purpose is to provide locally the libraries as well as the command-line utility: `gdiag`. -The command-line utility managed it-self the download of the PlantUML jar. +The NPM package [@tmorin/plantuml-libs](https://www.npmjs.com/package/@tmorin/plantuml-libs) provides the CLI commands as well as the packages +The CLI commands managed them-self the download of the PlantUML jar. -Install the package globally: +Install the NPM package globally: ```shell script npm i -g @tmorin/plantuml-libs ``` diff --git a/dist/README.md b/dist/README.md index 44e9f60dd34..c61b628dd96 100644 --- a/dist/README.md +++ b/dist/README.md @@ -41,22 +41,25 @@ Include locally the library: ## include vs !include -When documenting large projects, it often a good practice to define the components in separate `.puml` files which are then included in others containing the diagrams to render. -So that, the definition of the components can be re-used over the diagram. -Moreover, the diagrams which include them are automatically updated. +When documenting large projects, it's often a good practice to define the components in separate `.puml` files which will be then included in other `.puml` files containing the diagrams to render. +So that, the component definitions can be re-used among the diagrams. -However, be careful about relative and absolute paths with `!include` vs `include()`. -According to where you are (separate files vs diagram files), the _relative paths_ won't be resolve from the _current directory_. +However, be careful about relative and absolute paths with the usage of `!include` (the native PlantUML directive) vs `include()` (a custom procedure provided in this library). +According to where you are (i.e. reference files vs diagram files), the _relative paths_ won't be resolved from the _current directory_. Given the following file tree, the following snippets should help you to configure files properly. - project/ -- project/reference/c4.puml -- project/reference/aws.puml -- project/src/guidebook/component/c4.puml -- project/src/guidebook/component/aws.puml - -### project/reference/c4.puml + - ref/ + - c4.puml + - aws.puml + - src/ + - guidebook/ + - component/ + - c4.puml + - aws.puml + +### project/ref/c4.puml ```plantuml !global $INCLUSION_MODE="local" !global $LIB_BASE_LOCATION="../node_modules/@tmorin/plantuml-libs/dist" @@ -66,7 +69,7 @@ include('c4model/bootstrap') ' ..... ``` -### project/reference/aws.puml +### project/ref/aws.puml ```plantuml !global $INCLUSION_MODE="local" !global $LIB_BASE_LOCATION="../node_modules/@tmorin/plantuml-libs/dist" @@ -79,7 +82,7 @@ include('aws-20200911/bootstrap') ### project/src/guidebook/component/c4.puml ```plantuml @startuml level1-system -!include ../../../references/c4.puml +!include ../../../ref/c4.puml !global $IMAGE_BASE_PATH="../../" + $LIB_BASE_LOCATION + "/" !global $LIB_BASE_LOCATION="../../" + $LIB_BASE_LOCATION ' description of the diagram below @@ -90,7 +93,7 @@ include('aws-20200911/bootstrap') ### project/src/guidebook/component/aws.puml ```plantuml @startuml infrastructure-production -!include ../../../references/aws.puml +!include ../../../ref/aws.puml !global $IMAGE_BASE_PATH="../../" + $LIB_BASE_LOCATION + "/" !global $LIB_BASE_LOCATION="../../" + $LIB_BASE_LOCATION ' description of the diagram below diff --git a/lib/glib/template/library.md b/lib/glib/template/library.md index fd9939dcf86..4790fba28e4 100644 --- a/lib/glib/template/library.md +++ b/lib/glib/template/library.md @@ -34,22 +34,25 @@ Include locally the library: ## include vs !include -When documenting large projects, it often a good practice to define the components in separate `.puml` files which are then included in others containing the diagrams to render. -So that, the definition of the components can be re-used over the diagram. -Moreover, the diagrams which include them are automatically updated. +When documenting large projects, it's often a good practice to define the components in separate `.puml` files which will be then included in other `.puml` files containing the diagrams to render. +So that, the component definitions can be re-used among the diagrams. -However, be careful about relative and absolute paths with `!include` vs `include()`. -According to where you are (separate files vs diagram files), the _relative paths_ won't be resolve from the _current directory_. +However, be careful about relative and absolute paths with the usage of `!include` (the native PlantUML directive) vs `include()` (a custom procedure provided in this library). +According to where you are (i.e. reference files vs diagram files), the _relative paths_ won't be resolved from the _current directory_. Given the following file tree, the following snippets should help you to configure files properly. - project/ -- project/reference/c4.puml -- project/reference/aws.puml -- project/src/guidebook/component/c4.puml -- project/src/guidebook/component/aws.puml - -### project/reference/c4.puml + - ref/ + - c4.puml + - aws.puml + - src/ + - guidebook/ + - component/ + - c4.puml + - aws.puml + +### project/ref/c4.puml ```plantuml !global $INCLUSION_MODE="local" !global $LIB_BASE_LOCATION="../node_modules/@tmorin/plantuml-libs/dist" @@ -59,7 +62,7 @@ include('c4model/bootstrap') ' ..... ``` -### project/reference/aws.puml +### project/ref/aws.puml ```plantuml !global $INCLUSION_MODE="local" !global $LIB_BASE_LOCATION="../node_modules/@tmorin/plantuml-libs/dist" @@ -72,7 +75,7 @@ include('aws-20200911/bootstrap') ### project/src/guidebook/component/c4.puml ```plantuml @startuml level1-system -!include ../../../references/c4.puml +!include ../../../ref/c4.puml !global $IMAGE_BASE_PATH="../../" + $LIB_BASE_LOCATION + "/" !global $LIB_BASE_LOCATION="../../" + $LIB_BASE_LOCATION ' description of the diagram below @@ -83,7 +86,7 @@ include('aws-20200911/bootstrap') ### project/src/guidebook/component/aws.puml ```plantuml @startuml infrastructure-production -!include ../../../references/aws.puml +!include ../../../ref/aws.puml !global $IMAGE_BASE_PATH="../../" + $LIB_BASE_LOCATION + "/" !global $LIB_BASE_LOCATION="../../" + $LIB_BASE_LOCATION ' description of the diagram below