Documenting NST - Revision history

Paul Blankenbaker: /* The docs/docbook.css File */

2010-11-08T13:36:45Z

The docs/docbook.css File

← Older revision		Revision as of 09:36, 8 November 2010
Line 183:		Line 183:
	There are several things that should be noted in the ''docs/docbook.css'' file:		There are several things that should be noted in the ''docs/docbook.css'' file:

	* Colors can be applied based upon the original DocBook type. For example, the ''pre.screen'' adjusts the color settings for ''<pre>'' sections of the resulting HTML documents, but only if they are given the class of screen. To find the class of DocBook output, one needs to review the raw HTML produced by DocBook. Hint: Try viewing the source of this page and search for the string ''programlisting''.		* Colors can be applied based upon the original DocBook type. For example, the ''pre.screen'' adjusts the color settings for ''<pre>'' sections of the resulting HTML documents, but only if they are given the class of ''screen''. To find the class of DocBook output, one needs to review the raw HTML produced by DocBook. Hint: Try viewing the source of this page and then search for the string ''programlisting''.
	* The ''pre.programlisting'' defines a bitmap to be used for the background. The reference to the bitmap is relative to the location of the ''docbook.css'' file. Hence, the developer needs to be careful when adding bitmaps. It involves not only creating the actual bitmap, but also updating the make rules such that it will be installed in the proper location.		* The ''pre.programlisting'' defines a bitmap to be used for the background. The reference to the bitmap is relative to the location of the ''docbook.css'' file. Hence, the developer needs to be careful when adding bitmaps. It involves not only creating the actual bitmap, but also updating the make rules such that it will be installed in the proper location.

	= Adding New Documents =		= Adding New DocBook Documents =

	If you ~~are~~ a ~~developer interested in adding~~ new ~~documents~~ to the Network Security Toolkit project, there are a few basic steps to follow:		Since the DocBook generated documents tend to be static, they tend to become dated very quickly. Because of this, our general philosophy has been towards moving away from DocBook generated documents and creating new documents within the NST Wiki. So, the general rule of thumb is: "Don't create new DocBook documents".

			If you find yourself in a unique situation and really need to introduce a new DocBook document to the Network Security Toolkit project, there are a few basic steps to follow:

	* Create a new sub-directory for your document under the ''docs'' directory.		* Create a new sub-directory for your document under the ''docs'' directory.

Paul Blankenbaker: /* Building Just DocBook Documents */

2010-11-08T13:12:35Z

Building Just DocBook Documents

← Older revision		Revision as of 09:12, 8 November 2010
Line 70:		Line 70:
	[root@dhcp132 docs]#		[root@dhcp132 docs]#

	As the DocBook documents can take a long time to build, you may find yourself in the situation where you're saying "Dang, I wish there was a way to just build this one document!" Well, your lucky day has come. You can invoke ''make help'' under the ''docs'' directory (be prepared to pipe this into less) to see all of the individual documents that can be built. To use this feature, you should ~~invoke the~~ make setup at least once (this will install the shared files for you). For example, to build JUST the HTML version of the ''wepquest'' document:		As the DocBook documents can take a long time to build, you may find yourself in the situation where you're saying "Dang, I wish there was a way to just build this one document!" Well, your lucky day has come. You can invoke "'''make help'''" under the ''docs'' directory (be prepared to pipe this into '''less''') to see all of the individual documents that can be built. To use this feature, you should run: "'''make setup'''" at least once (this will install the shared files for you). For example, to build JUST the HTML version of the ''wepquest'' document:

	[root@dhcp132 trunk]# cd docs		[root@dhcp132 trunk]# cd docs

Paul Blankenbaker: /* Building Just DocBook Documents */

2010-11-08T13:11:32Z

Building Just DocBook Documents

← Older revision		Revision as of 09:11, 8 November 2010
Line 65:		Line 65:
	To build JUST the DocBook documents:		To build JUST the DocBook documents:

	[~~pkb~~@~~salsa pkb~~]$ cd ~~$HOME/nst/~~docs		[root@dhcp132 trunk]# cd docs
	[~~pkb~~@~~salsa~~ docs]$ make		[root@dhcp132 docs]# make
			... Lots of output as documents are built ...
			[root@dhcp132 docs]#

	As the DocBook documents can take a long time to build, you may find yourself in the situation where you're saying "Dang, I wish there was a way to just build this one document!" Well, your lucky day has come. You can invoke ''make help'' under the ''docs'' directory (be prepared to pipe this into less) to see all of the individual documents that can be built. To use this feature, you should invoke the make setup at least once (this will install the shared files for you). For example, to build JUST the HTML version of the ''wepquest'' document:		As the DocBook documents can take a long time to build, you may find yourself in the situation where you're saying "Dang, I wish there was a way to just build this one document!" Well, your lucky day has come. You can invoke ''make help'' under the ''docs'' directory (be prepared to pipe this into less) to see all of the individual documents that can be built. To use this feature, you should invoke the make setup at least once (this will install the shared files for you). For example, to build JUST the HTML version of the ''wepquest'' document:
Line 80:		Line 82:
	Writing bi01.html for bibliography		Writing bi01.html for bibliography
	Writing index.html for article		Writing index.html for article
	[root@dhcp132 docs]# firefox ../tmp/public_html/nst/docs/wepquest/index.html		[root@dhcp132 docs]# firefox ../tmp/public_html/nst/docs/wepquest/index.html

	== Building Just The HTML Documents ==		== Building Just The HTML Documents ==

Paul Blankenbaker: /* Viewing The Documents */

2010-11-08T13:10:02Z

Viewing The Documents

← Older revision		Revision as of 09:10, 8 November 2010
Line 46:		Line 46:
	Allow from all		Allow from all
	</Directory>		</Directory>

	Alias /nst /opt/trunk/tmp/public_html/nst		Alias /nst /opt/trunk/tmp/public_html/nst
	Alias /nstweb /opt/trunk/tmp/public_html/nst		Alias /nstweb /opt/trunk/tmp/public_html/nst

Paul Blankenbaker: /* Building NST Documentation */

2010-11-08T13:09:17Z

Building NST Documentation

← Older revision		Revision as of 09:09, 8 November 2010
Line 28:		Line 28:
	By default, the documents will be placed under the directories ''tmp/public_html/nst'' and ''tmp/public_html/nstwui'' under the source directory.		By default, the documents will be placed under the directories ''tmp/public_html/nst'' and ''tmp/public_html/nstwui'' under the source directory.

	[[File:Warning.png]] After you are done building documentation, make sure you run a top-level '''./configure''' to reset the system so that the '''nstweb''' ~~package~~ will be built correctly for inclusion on a ISO build.		[[File:Warning.png]] After you are done building documentation, make sure you run a top-level '''./configure''' to reset the system so that the '''nstweb''' and '''nstwui''' packages will be built correctly for inclusion on a ISO build.

	== Viewing The Documents ==		== Viewing The Documents ==

Paul Blankenbaker: /* Background */

2010-11-08T13:08:05Z

Background

← Older revision		Revision as of 09:08, 8 November 2010
Line 7:		Line 7:
	* The DocBook documents associated with each NST script. These are primarily used for man page and HTML rendered output.		* The DocBook documents associated with each NST script. These are primarily used for man page and HTML rendered output.
	* The ''static'' HTML web pages resembling the NST WUI. These are found on the Internet at: http://www.networksecuritytoolkit.org/. These are also found on a NST system in the '''nstweb''' package.		* The ''static'' HTML web pages resembling the NST WUI. These are found on the Internet at: http://www.networksecuritytoolkit.org/. These are also found on a NST system in the '''nstweb''' package.
	* The ''static'' DocBook documents (found under the ''docs'' sub-directory on a development system). These documents tend to become ~~sorely~~ outdated.		* The ''static'' DocBook documents (found under the ''docs'' sub-directory on a development system). These documents tend not be maintained and become outdated.

	= Requirements =		= Requirements =

Paul Blankenbaker: Created page with '= Background = There are many types of documents associated with the NST project. * The NST Wiki (http://wiki.networksecuritytoolkit.org/) contains a lot of the documentation r…'

2010-11-08T13:07:05Z

Created page with '= Background = There are many types of documents associated with the NST project. * The NST Wiki (http://wiki.networksecuritytoolkit.org/) contains a lot of the documentation r…'

New page

= Background =

There are many types of documents associated with the NST project.

* The NST Wiki (http://wiki.networksecuritytoolkit.org/) contains a lot of the documentation related to the project and is the easiest to maintain.
* The NST Web User Interface (WUI) contains a lot of documentation within the tools used to manage the NST. These are found in the '''nstwui''' package on a NST system.
* The DocBook documents associated with each NST script. These are primarily used for man page and HTML rendered output.
* The ''static'' HTML web pages resembling the NST WUI. These are found on the Internet at: http://www.networksecuritytoolkit.org/. These are also found on a NST system in the '''nstweb''' package.
* The ''static'' DocBook documents (found under the ''docs'' sub-directory on a development system). These documents tend to become sorely outdated.

= Requirements =

== Building NST Documentation ==

In order to build the ''static'' NST documentation, you need to run the top level '''configure''' script with the ''--on-line-docs'' option:

./configure --on-line-docs

The above command will make the following changes to your build system:

* It will change the way the '''nstweb''' package is built.
* It will enable the building of the DocBook documents found under the ''docs/'' sub-directory.

After configuring your development environment for the purpose of building the NST documentation, you should be able to run the following command to build the ''static'' NST documents:

make docs

By default, the documents will be placed under the directories ''tmp/public_html/nst'' and ''tmp/public_html/nstwui'' under the source directory.

[[File:Warning.png]] After you are done building documentation, make sure you run a top-level '''./configure''' to reset the system so that the '''nstweb''' package will be built correctly for inclusion on a ISO build.

== Viewing The Documents ==

To view the results of a local build of the Documentation, you will need to add a Apache configuration file ''/etc/httpd/conf.d/nstweb.conf''. You will need to set the ''Directory'' and ''Alias'' values to match the output directory of your build. The example below is for a output directory of ''/opt/trunk/tmp/public_html/nst'':

# nstweb - A snapshot (typically reduced) of the
# www.networksecurity.toolkit web site.
#
# Requires NST authentication and SSL access if not on localhost

#<Directory /usr/share/nstweb/>
<Directory /opt/trunk/tmp/public_html/nst/>
DirectoryIndex index.php index.html
Options Indexes FollowSymLinks -ExecCGI -Includes
Order allow,deny
Allow from all
</Directory>

Alias /nst /opt/trunk/tmp/public_html/nst
Alias /nstweb /opt/trunk/tmp/public_html/nst

After creating the above configuration file, you will need to restart the web server:

[root@dhcp132 ~]# service httpd restart
Stopping httpd: [ OK ]
Starting httpd: [ OK ]
[root@dhcp132 ~]#

At this point you should be able to review the documentation using a web browser. Use the URL of "http://IP_ADDRESS/nst" where ''IP_ADDRESS'' is the IP address of your development system.

== Building Just DocBook Documents ==

You can build portions of the documentation individually.

To build JUST the DocBook documents:

[pkb@salsa pkb]$ cd $HOME/nst/docs
[pkb@salsa docs]$ make

As the DocBook documents can take a long time to build, you may find yourself in the situation where you're saying "Dang, I wish there was a way to just build this one document!" Well, your lucky day has come. You can invoke ''make help'' under the ''docs'' directory (be prepared to pipe this into less) to see all of the individual documents that can be built. To use this feature, you should invoke the make setup at least once (this will install the shared files for you). For example, to build JUST the HTML version of the ''wepquest'' document:

[root@dhcp132 trunk]# cd docs
[root@dhcp132 docs]# make setup
... Lots of output to screen ...
[root@dhcp132 docs]# make wepquest.html
(cd /opt/trunk/tmp/public_html/nst/docs/wepquest && /usr/bin/xsltproc /opt/trunk/docs/chunk.xsl "/opt/trunk/docs/wepquest/book.xml" >| "/opt/trunk/tmp/public_html/nst/docs/wepquest/index.html")
Writing ar01s02.html for section
Writing ar01s03.html for section
Writing ar01s04.html for section
Writing bi01.html for bibliography
Writing index.html for article
[root@dhcp132 docs]# firefox ../tmp/public_html/nst/docs/wepquest/index.html

== Building Just The HTML Documents ==

If your development environment is set up correctly, you can build and view just the static HTML documents using the following commands:

[root@dhcp132 trunk]# cd html
[root@dhcp132 html]# make
... Lots of output ...
[root@dhcp132 html]# firefox http://127.0.0.1/nst

= Tweaking the DocBook HTML Output =

It took a long time to figure this out, but we finally managed to adjust the output of the HTML pages generated when compiling DocBook files. In order to do this, we needed to:

* Create a custom ''chunk.xsl'' style sheet.
* Create a custom ''docbook.css'' file - which controls how the various parts of a document are rendered.
* Create and install auxiliary files (bitmaps) referenced by the above two files.

== The ''docs/chunk.xsl'' File ==

In order to tweak the HTML produced by our DocBook source files, we needed to create a custom XSL style sheet. This custom file includes the normal DocBook formatting rules, and then adjusts a few settings to our liking (we were particularily interested in the inclusion of a custom CSS file). The ''docs/chunk.xsl'' is built from code within the '''docs/configure''' shell script. If you want to make permanent changes, you will need to modify '''docs/configure'''. The following shows the contents of '''docs/chunk.xsl''' at the time this document was created:

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version='1.0'>



<xsl:import href="file:///usr/share/sgml/docbook/xsl-stylesheets-1.75.2/xhtml/chunk.xsl"/>



<xsl:param name="html.stylesheet">../docbook.css</xsl:param>



<xsl:param name="header.rule" select="0"></xsl:param>
<xsl:param name="footer.rule" select="0"></xsl:param>



<xsl:param name="make.graphic.viewport" select="1"></xsl:param>
<xsl:param name="ignore.image.scaling" select="1"></xsl:param>



<xsl:param name="ulink.target" select="'_self'"></xsl:param>



<xsl:param name="entry.propogates.style" select="1" />
<xsl:param name="emphasis.propogates.style" select="1" />
<xsl:param name="para.propogates.style" select="1" />
<xsl:param name="phrase.propogates.style" select="1" />



<xsl:param name="html.cleanup" select="1" />
<xsl:param name="make.valid.html" select="1" />



<xsl:param name="callout.graphics" select="'1'" />
<xsl:param name="callouts.extension" select="'1'" />
<xsl:param name="callout.graphics.path" select="'../images/callouts/'" />


<xsl:template name="user.head.content">
<meta xmlns="http://www.w3.org/1999/xhtml" http-equiv="Content-Type"
content="text/html; charset=UTF-8" />
</xsl:template>

</xsl:stylesheet>

There are many "dials" that can be adjusted in the ''docs/chunk.xsl'' file. To learn more about these various settings, read the [http://docbook.sourceforge.net/release/xsl/current/doc/html/index.html DocBook HTML Parameter Reference]. Also, you may want to try searching Google for [http://www.google.com/search?q=%2B%22Customizing+DocBook+XSL+stylesheets%22&sourceid=mozilla-search&start=0&start=0&ie=utf-8&oe=utf-8 Customizing DocBook XSL stylesheets].

== The ''docs/docbook.css'' File ==

If you examine the ''docs/chunk.xsl'', you'll notice that it specifies a custom ''html.stylesheet''. This CSS file is found at ''docs/docbook.css'' and controls the colors, fonts and formatting of the HTML pages.

There are several things that should be noted in the ''docs/docbook.css'' file:

* Colors can be applied based upon the original DocBook type. For example, the ''pre.screen'' adjusts the color settings for ''<pre>'' sections of the resulting HTML documents, but only if they are given the class of screen. To find the class of DocBook output, one needs to review the raw HTML produced by DocBook. Hint: Try viewing the source of this page and search for the string ''programlisting''.
* The ''pre.programlisting'' defines a bitmap to be used for the background. The reference to the bitmap is relative to the location of the ''docbook.css'' file. Hence, the developer needs to be careful when adding bitmaps. It involves not only creating the actual bitmap, but also updating the make rules such that it will be installed in the proper location.

= Adding New Documents =

If you are a developer interested in adding new documents to the Network Security Toolkit project, there are a few basic steps to follow:

* Create a new sub-directory for your document under the ''docs'' directory.
* Create the DocBook file ''book.xml'' and place it in your new sub-directory.
* Install any supporting XML or image files for your document into the new sub-directory.
* Run the '''configure''' script found in the ''docs'' directory to update the ''Makefile'' rules for your new document.
* Run '''make setup''' to prepare the system to build your new document.