Part of the sgml-tools system is a perl module called Html2Html.pm.
When you activate the option --nice (or -N), instead of Html2Html.pm, a new module called niceHtml2Html.pm is used.
In order to understand how to use effeciently the --nice option you have to know exactly what Html2Html.pm is doing.
When you format an sgml document with sgml2html, it is filtered using some programs, in such way that the sgml tags defined in the appropriate dtd (Document Type Description) are replaced by html tags.
This could be straight-forward but the problem is that the output of sgml2html is not one file; the document is split to several files, as many as the sections it contains. This makes sense; you wouldn't want to download a whole book from your browser, just to read the "credits" section!
This is what causes the main trouble; the internal links are destroyed and they must be redefined so that they point to the right file. This is a job for Html2Html.pm. This is why if you take a look at html/mapping you will see that some sgml tags are not replaced by html tags but by strange <@@abcd> tags. Those tags are important for Html2Html.pm.
Html2Html.pm adds more value to your documents by creating a Table of Contents and taking care of some other little thing like the navigation icons or words that appear at the top and bottom of each page and point to the next and previous section as well as to the Table of Contents.
What Html2Html.pm creates is a fully functional set of html documents.
The body of each document starts with the buttons mentioned above (either as text or iconic) and goes on with the text of your document.
niceHtml2Html.pm is a hacked version of Html2Html.pm. It does all what the original Html2Html does plus, it inserts user-defined html tags at certain critical sections of the document. Those are:
We will call SectionA the section between the </TITLE> tag and the </HEAD> tag. Here is where we may insert <META> tags or any other tag that could go in the HEAD of an html document.
SectionB is between </HEAD> tag and the first line of our document. Note that the <BODY> tag belongs to SectionB.
SectionC is just before the </BODY> tag.
BarTags1 are the tags inserted just before the navigation buttons and BarTags2 are inserted just after them.
So, your resulting document will look like this:
<HTML>
<HEAD>
<TITLE>The test document</TITLE>
---------------->PartA
</HEAD>
---------------->PartB
containing <BODY>
---------------->BarTags1
(The buttons)
---------------->BarTags2
(The text of the document)
---------------->BarTags1
(The buttons)
---------------->BarTags2
---------------->PartC
</BODY>
</HTML>
The advantages are obvious! You can define in an important degree the look of your document.