// to display images directly on GitHub
ifdef::env-github[]
:encoding: UTF-8
:lang: en
:doctype: book
:toc: left
:imagesdir: ../images
endif::[]

////

    This file is part of the PacketFence project.

    See PacketFence_Developers_Guide.asciidoc
    for authors, copyright and license information.

////

//== Documentation

The in-depth or more technical documentation is always as close to the code as possible. Always look at the `POD` doc footnote:[Perl's Plain Old Documentation: http://perldoc.perl.org/perlpod.html]. To do so, the preferred way is using the `perldoc` command as follows:

  perldoc lib/pfconfig/cached.pm


== Asciidoctor documentation

=== Documentation Conventions

==== Shell commands in code blocks

.To ease copy-paste of shell commands:
* Remove useless characters in code blocks like `#` or `$`
* Split long lines with `\`

==== Titles

We use Asciidoctor tags for section titles (headings) in place of AsciiDoc tags, see table below for equivalence:


.Compatibility between AsciiDoc and Asciidoctor syntax for section titles
|===
|Level |AsciiDoc syntax (old) |Asciidoctor syntax (new)

|Level 0 (Document title)
|`=====`
|`=`

|Level 1
|`-----`
|`==`

|Level 2
|`~~~~~`
|`===`

|Level 3
|`^^^^^`
|`====`

|Level 4
|`+++++`
|`=====`
|===

==== Other Conventions

\* (asterisk) for important vocabulary. Ex: \*This Part* is important

_ (underscore) for menus. Ex: \_Configuration -> Policies and Access Control -> Connection Profile -> Profile Name_

backquotes ` for buttons. Ex: Click on \`Save`

==== Inter-document cross references

We use link:https://asciidoctor.org/docs/user-manual/#inter-document-cross-references[inter-document cross references feature] to make links between all PacketFence guides. When we need to link to a specific section of a document, we use link:https://asciidoctor.org/docs/user-manual/#automatic-anchors[automatic anchors feature] to have a correct display in PDF.

==== List of Asciidoctor tags used

Source: link:https://redhat-documentation.github.io/asciidoc-markup-conventions/[AsciiDoc Mark-up Quick Reference for Red Hat Documentation]

[NOTE]
====
Some markup examples used in this overview are based on new Asciidoctor features and they are not a part of the standard set of elements. Please, use the `:experimental:` tag in the header of your document to enable this functionality.
====

[width="100%",cols="3,4,4"]
|===
|Element|Mark-up|Example rendered output

|Application name
a|No special markup
a| The foo application.

|Code blocks
a|
....
[source,golang]
----
package main

import "fmt"

func main() {
	fmt.Println("Hello World !")
}
----
....

a|
[source,golang]
----
package main

import "fmt"

func main() {
	fmt.Println("Hello World !")
}
----

|Code - inline
a|
....
`print("Hello, World!")`
....

a| `print("Hello, World!")`

|Command block
a|
....
----
$ echo "Hello, World!" > hello.txt
----
....
a|
----
$ echo "Hello, World!" > hello.txt
----

|Command - inline
a|
....
Use the [command]`oc get` command to get a list of services.
....

a|Use the [command]`oc get` command to get a list of services.

|Emphasis for a term
a|
....
Use _this_ approach.
....

a|Use _this_ approach.

|===


[width="100%",cols="3,4,4"]
|===
|Element|Mark-up|Example rendered output

|Filenames or directory paths

a|
....
Edit the [filename]`pf.conf` file as required and save your changes.

The [filename]`networks.conf` configuration file is located in the [filename]`/usr/local/pf/` directory.
....

a|Edit the [filename]`pf.conf` file as required and save your changes.

The [filename]`networks.conf` configuration file is located in the [filename]`/usr/local/pf/` directory.

|===


[width="100%",cols="3,4,4"]
|===
|Element|Mark-up|Example rendered output

|GUI Text

a|
....
The web browser displays *404* for an unreachable URL.
....

a|The web browser displays *404* for an unreachable URL.

|GUI Button (experimental feature, Asciidoctor only)
a|
....
Click btn:[Save As] to save the file under a different name.
....

a|Click btn:[Save As] to save the file under a different name.

|GUI Menu (experimental feature, Asciidoctor only)

a|
....
Navigate to menu:File[Import>Import csv] to import a csv file.
....

a|Navigate to menu:File[Import>Import csv] to import a csv file.

|GUI button and menu (non-experimental)

a|
....
Navigate to _Configuration -> Policies and Access Control_
....

a|Navigate to _Configuration -> Policies and Access Control_

|===


[width="100%",cols="3,4,4"]
|===
|Element|Mark-up|Example rendered output

|Inline Image

a|
....
image::pf-logo.png[width=25px]
....

a| image::pf-logo.png[width=25px]

| Block Image
a|
....
.PacketFence
image::pf-logo.png[width=25px]
....
a| .PacketFence
image::pf-logo.png[width=25px]

|Inline operations and user input

a|
....
The `GET` operation can be used to do something.

Answer by typing `Yes` or `No` when prompted.
....

a|The `GET` operation can be used to do something.

Answer by typing `Yes` or `No` when prompted.

|===


[width="100%",cols="3,4,4"]
|===
|Element|Mark-up|Example rendered output

| Keyboard shortcuts (experimental feature, Asciidoctor only)
a|
....
kbd:[Ctrl+Alt+Del]
....
a| kbd:[Ctrl+Alt+Del]

|===


[width="100%",cols="3,4,4"]
|===
|Element|Mark-up|Example rendered output

| Link (external)

a|
....
link:http://www.packetfence.org[PacketFence]
....

a| link:http://www.packetfence.org[PacketFence]

|===


[width="100%",cols="3,4,4"]
|===
|Element|Mark-up|Example rendered output

a|Lists

NOTE: Do not put steps in bold.

a|

....
.Ordered list

. First item
. Second item
. Third item

.Unordered list

* This
* That
* The other

.Definition or labeled list

Term A:: description
Term B:: description

.Checklist
* [ ] first step
** [ ] first task
** [ ] second task
* [ ] second step
* [ ] third step
....

a|.Ordered list

. First item
. Second item
. Third item

.Unordered list

* This
* That
* The other

.Definition  or labeled list

Term A:: description
Term B:: description

.Checklist
* [ ] first step
** [ ] first task
** [ ] second task
* [ ] second step
* [ ] third step

|===


[width="100%",cols="3,4,4"]
|===
|Literal value

a|
....
The function returns `true`.
....

a|The function returns `true`.


|===


[width="100%",cols="3,4,4"]
|===
|Element|Mark-up|Example rendered output

|Package
a|
....
Install the [package]`packetfence` package.
....

a|Install the [package]`packetfence` package.

|Product name
a|No special markup. Use +++{nbsp}+++ in the company and product names. Example: Inverse+++{nbsp}+++Inc.
a|Inverse{nbsp}Inc.

|Reference to PacketFence guides
a|
....
See the PacketFence link:guide-url[_Installation Guide_] for more information.
....

a|See the PacketFence link:guide-url[_Installation Guide_] for more information.

|System or software variable to be replaced by the user
a|
....
Use the following command to roll back a deployment, specifying the deployment name: `oc rollback _deployment_`.
....

a|
Use the following command to roll back a deployment, specifying the deployment name: `oc rollback _deployment_`.


|System or software configuration parameter or environment variable
a|
....
Use the `_IP_ADDRESS_` environment variable for the server IP address.
....

a|Use the `_IP_ADDRESS_` environment variable for the server IP address.

|System item, daemon, or service

a|
....
Include the `pf::Switch` library.

Stop the `pfqueue` daemon.

Start the `iptables` service.
....

a|Include the `pf::Switch` library.

Stop the `pfqueue` daemon.

Start the `packetfence-iptables` service.

|===


=== Checklist to create a new guide

* [ ] create PacketFence_GUIDENAME.asciidoc based on PacketFence link:PacketFence_Template_Guide.asciidoc[_Template Guide_]
* [ ] update `all` target in Makefile
* [ ] update packaging (if necessary)
* [ ] update website listing to add a new guide
