README for the swbis Documentation

The contents of the ./source directory are the source.

The contents of ./info ./html ./man ./texi are generated
from the source, therefore always make changes to files
in ./source.  Changes to files in ./texi ./info ./man 
./html will be lost.
  
The root of the info tree is info/swbis.info
You can read it without installing by

     info -f info/swbis.info

The root of the html tree is html/swbis.html 

Making the documentation
------------------------
The official documentation is made on a Debian 3.1 system using
the packages described below.  Several packages are patched with
the patches show below.

To delete all generated files and remake from scratch do:   
	make realclean text man info html  # In this directory

BUG:
The sgml source files produce so many warnings that
you may have to edit the sgml parser wrapper shell script (which launches the
sgml parser) to allow more parser warnings before quitting with an
error (This is a command line switch to the parser found in the
shell script).

You will need the following packages:

3991798ddca05a72fbe7c8dfb10c50c1  docbk241.tar.Z
96489411b5f1aff644abc12ef50510e7  man2texi-0.01.tar.bz2
ccefdac569c96641ee8f67cf99eb0ef4  yman2html-0_22.tar.gz
b28ddaaa8eb4b775100c67fd1205240a  docbook-to-man.tar.gz
[uncompressed  ad8499879f076b301893724081b12f2e  docbook-to-man.tar]

docbook-to-man is a free tool from the OSF.
docbk241.tar.Z is the docbook DTD v2.41 package from Davenport Co.

Compiling the documentation on a modern Debian System:
-------------------------------------------------------

The documentation can be compiled on Debian GNU/Linux 3.1r0a
with the following additions/changes:

Add the man2texi and yman2html-0_22 packages

Then, install the Debian docbook-to-man package (which is part of the
Debian distribution, it was on CD#3 of my CD set) then modify the
docbook-to-man shell script, /usr/bin/docbook-to-man, and the translation
spec file as indicated by the following patch:

--- docbook-to-man.orig	2005-01-07 09:18:19.000000000 -0500
+++ docbook-to-man	2005-09-04 21:18:02.277772736 -0400
@@ -177,10 +177,9 @@
 #fi
 
 (#cat /tmp/dtm.$$.psinc;
- $PARSER -gl -m$CATALOG $DECL $INSTANCE |
+ $PARSER -E 5000 -gl -m$CATALOG $DECL $INSTANCE |
 	$INSTANT -croff.cmap -sroff.sdata -tdocbook-to-man.ts $INSTANT_OPT |
-	sed 's/^[	 ]*//
-	     s/$/ /
+	sed 's/$/ /
 	     s/--/\\-\\-/g
 	     s/^-/\\-/
 	     s/\([^A-Za-z0-9\-]\)-/\1\\-/g' )

Then modify the '/usr/share/sgml/transpec/docbook-to-man.ts' file according to
the patch below.  Note, this change reverts some of the changes made by the ANS
Modifications back to being in line with Fred Dalrymple's original package.

# diff -u /usr/share/sgml/transpec/docbook-to-man.ts.deb-sarge /usr/share/sgml/transpec/docbook-to-man.ts
--- /usr/share/sgml/transpec/docbook-to-man.ts.deb-sarge        2005-01-07 09:18:19.000000000 -0500
+++ /usr/share/sgml/transpec/docbook-to-man.ts  2005-09-05 18:32:00.000000000 -0400
@@ -1699,8 +1699,7 @@
 #
 GI:            COMMAND
 StartText:     \\fB
-#EndText:      \\fP
-EndText:       \\fR
+EndText:       \\fP
 -
 #
 GI:            COMPUTEROUTPUT
@@ -1850,8 +1849,7 @@
 #
 GI:            REPLACEABLE
 StartText:     \\fI
-#EndText:      \\fP
-EndText:       \\fR
+EndText:       \\fP
 -
 #
 GI:            RETURNVALUE

<-- End of patch
TO MAKE RAGGED RIGHT EDGE AND TURN OF HYPHENATION
-------------------------------------------------
.hy 0
.if n .na


MAN2TEXI PATCH TO WRITE THE MENU AT THE END OF THE NODE
--------------------------------------------------------
Here's the patch to man2texi.  It is optional. Using this
patch places the menu at the end of the texi documents "@node".
This the the preferred way.

diff -ruN man2texi-0.01/man2texi.awk man2texi-0.01-jhl1/man2texi.awk
--- man2texi-0.01/man2texi.awk	2002-12-23 21:16:36.000000000 -0500
+++ man2texi-0.01-jhl1/man2texi.awk	2006-05-18 22:21:30.000000000 -0400
@@ -39,7 +39,10 @@
 
 						{ copy($0); next }
 
-END						{ terminate() }
+END						{ 
+							#terminate() 
+							terminate2() 
+						  }
 
 ### ====================================================================
 
@@ -431,6 +434,7 @@
 	begin_environment("quotation")
     else if (s ~ "^[.]SH")
     {
+        writeln("@comment MAN2TEXI: EON")
 	end_open_environments()
 	t = unquote(substr(s,4))
 	add_menu("Top",t)
@@ -441,6 +445,7 @@
     }
     else if (s ~ "^[.]SS")
     {
+        writeln("@comment MAN2TEXI: EON")
 	end_open_environments()
 	t = unquote(substr(s,4))
 	add_menu(Section,t)
@@ -480,7 +485,6 @@
 	writeln("@comment " s)
 }
 
-
 function terminate( k)
 {
     end_open_environments()
@@ -495,6 +499,28 @@
     }
 }
 
+function terminate2( k)
+{
+    key=""
+    end_open_environments()
+    writeln("@bye")
+    for (k = 1; k < Nlines; ++k)
+    {
+	if (Lines[k] ~ "@chapter") {
+	    key="Top"
+	    printf("%s", Lines[k])
+	} else if (Lines[k] ~ "@section") {
+	    key=trim_newline(substr(Lines[k],9))
+	    printf("%s", Lines[k])
+	} else if (Lines[k] ~ /@comment MAN2TEXI: EON/) {
+	    if (key != "") print_menu(key)
+	    printf("%s", Lines[k])
+	    key=""
+    	} else {
+	    printf("%s", Lines[k])
+	}
+    }
+}
 
 function trim(s)
 {

<-- End of patch

-- END of README
