Document --css-based-on-bootstrap, merge "example css" into CssOption

Author: michaliskambi

src/CommandLine.asciidoc

@@ -123,7 +123,7 @@ Obsolete name for --link-look=full option.
 link:AutoAbstractOption[--auto-abstract]::
 Automatically deduce @abstract description of item from 1st sentence of it's full description
 
-link:CssOption[--css]::
+link:CssOption[--css, --css-based-on-bootstrap]::
 Use the code of your cascading style sheet in replacement of default one.
 
 link:UseTipueSearchOption[--use-tipue-search]::

src/CssOption.asciidoc

@@ -1,13 +1,34 @@
-:doctitle: --css command-line option
+:doctitle: --css, --css-based-on-bootstrap command-line options
 
-By default, pasdoc generates a pasdoc.css file in the generated
-documentation in link:HtmlOutput[HTML] and link:HtmlHelp[HtmlHelp]
-formats.
+## Introduction
 
-If you want to use your own style sheet, you can use the
-link:CommandLine[CommandLine] option --css=CSS-FILE-NAME. Then pasdoc
-will simply copy the given file CSS-FILE-NAME to the output directory as
-pasdoc.css.
+You can control what your link:HtmlOutput[HTML] and link:HtmlHelp[HtmlHelp]
+documentation looks like by tweaking the CSS file.
 
-You can find some alternative stylesheets on
-link:PasDocCssExamples[PasDocCssExamples].
+To use your own style sheet, use the link:CommandLine[CommandLine] option:
+
+- `--css=CSS-FILE` to provide a new CSS file (that does _not_ rely on standard Bootstrap CSS classes, so Bootstrap will not be used in the output).
+
+- `--css-based-on-bootstrap=CSS-FILE` to provide a new CSS file that _does_ rely on standard Bootstrap CSS classes. So Bootstrap will be used in the output.
+
+## Default CSS
+
+The https://github.com/pasdoc/pasdoc/blob/master/source/component/pasdoc.css[default pasdoc.css is here]. Note that it relies on Bootstrap, so if you tweak it, provide the new version using link:Css[--css-based-on-bootstrap] command-line option.
+
+The old `pasdoc.css` that does not rely on Bootstrap is here: https://github.com/pasdoc/pasdoc/blob/master/source/component/alternative_css/pasdoc-up-to-0.16.0.css[source/component/alternative_css/pasdoc-up-to-0.16.0.css]. You can tweak it, and provide the new version using link:Css[--css] command-line option.
+
+## Alternative CSS
+
+We provide some alternative CSS styles in the https://github.com/pasdoc/pasdoc/tree/master/source/component/alternative_css/[source/component/alternative_css/] directory of the PasDoc repository.
+
+Use them directly as a starting point for your own CSS styles.
+
+Examples:
+
+```
+pasdoc *.pas -css=source/component/alternative_css/AscanioPressato.css
+
+pasdoc *.pas -css=source/component/alternative_css/ThomasMueller.css
+
+pasdoc *.pas -css=source/component/alternative_css/pasdoc-up-to-0.16.0.css
+```

src/HtmlHeadBodyBeginEndOptions.asciidoc

@@ -8,7 +8,7 @@ These three command-line options insert custom HTML code to every generated page
 
 They offer you a lot of possibilities:
 
-* In `--html-head` you can add links to additional CSS files. (Remember that you can also _replace_ the original CSS code using link:CssOption[--css] option.)
+* In `--html-head` you can add links to additional CSS files. (Remember that you can also _replace_ the original CSS code using link:CssOption[--css or --css-based-on-bootstrap] options.)
 * You can add links to external JavaScript files. Some of them should to `--html-head`, some to `--html-body-end`. Consult the documentation of the particular JavaScript code.
 * You can add navigation panel to the top and/or bottom of every page.
 * Using both `--html-body-begin` and `--html-body-end` you can wrap the whole PasDoc content in an additional container (like `<div class="pasdoc-container">...</div>`). This can be useful e.g. to style the content selectively, or add a custom sidebar to it.

src/HtmlOutput.asciidoc

@@ -14,12 +14,9 @@ Some details about HTML output:
 
 ## [[css]] CSS
 
-The look of HTML output is controlled by CSS code in pasdoc.css file,
+The look of HTML output is controlled by CSS code in `pasdoc.css` file,
 generated by pasdoc while making HTML output. You can customize how your
-documentation looks by modifying this file. See
-http://www.w3.org/Style/CSS/[W3C resources about CSS]. See also
-link:PasDocCssExamples[example alternative CSS styles for pasdoc]
-that you can use.
+documentation looks by providing your own CSS file using link:CssOption[--css or --css-based-on-bootstrap] command-line options.
 
 ## [[html-standard-conformance]] HTML standard conformance