LDP
/
LDP
mirror of https://github.com/tLDP/LDP
0
1
Fork 0
Code Releases Activity

updated

This commit is contained in:
gferg 2001-01-18 14:37:02 +00:00
parent 6b4810f5bf
commit 358b2f5dc4
3 changed files with 373 additions and 415 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

535
LDP/howto/docbook/Boca.sgml
View File

@ -1,268 +1,267 @@
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
<article ID="BocaCard"> <article ID="BocaCard">
<articleinfo> <articleinfo>
<title>Installing Boca Card Mini-HOWTO</title> <title>Installing Boca Card Mini-HOWTO</title>
<author> <author>
<firstname>David H.</firstname> <firstname>David H.</firstname>
<surname>Dennis</surname> <surname>Dennis</surname>
<affiliation> <affiliation>
<address> <email>david@amazing.com</email> </address> <address> <email>david@amazing.com</email> </address>
</affiliation> </affiliation>
</author> </author>
<abstract> <abstract>
<para>Describes the basics of a Boca 16-port Serial Card (Boca 2016) <para>Describes the basics of a Boca 16-port Serial Card (Boca 2016)
used with Linux. </para> used with Linux. </para>
</abstract> </abstract>
<pubdate>2001-??-01</pubdate> <pubdate>2001-17-01</pubdate>
<revhistory> <revhistory>
<revision> <revision>
<revnumber>1.0</revnumber> <revnumber>1.0</revnumber>
<date>1997-07-08</date> <date>1997-07-08</date>
<authorinitials>DHD</authorinitials> <authorinitials>DHD</authorinitials>
</revision> </revision>
</revhistory> </revhistory>
<othercredit role="converter"> <othercredit role="converter">
<firstname>Joy</firstname> <firstname>Joy</firstname>
<surname>Yokley</surname> <surname>Yokley</surname>
<contrib>Converted document from HTML to DocBook v4.1 (SGML)</contrib> <contrib>Converted document from HTML to DocBook v4.1 (SGML)</contrib>
</othercredit> </othercredit>
</articleinfo> </articleinfo>
<sect1 ID="Introduction"> <sect1 ID="Introduction">
<title>Introduction</title> <title>Introduction</title>
<para>This HOWTO is being maintained by David H Dennis, <para>This HOWTO is being maintained by David H Dennis,
david@amazing.com, to try and help any other individuals who may have acquired david@amazing.com, to try and help any other individuals who may have acquired
a BocaBoard, stared at it and found out that it didn't seem to do a BocaBoard, stared at it and found out that it didn't seem to do
anything.</para> anything.</para>
<para>A very high percentage of those interested in the BocaBoard are <para>A very high percentage of those interested in the BocaBoard are
also interested in becoming Internet Service Providers (ISPs). If you are one also interested in becoming Internet Service Providers (ISPs). If you are one
of them, please feel free to drop by my web site, of them, please feel free to drop by my web site,
<ulink URL="http://www.amazing.com"> http://www.amazing.com</ulink>, <ulink URL="http://www.amazing.com"> http://www.amazing.com</ulink>,
and check out my Inet-Access FAQ, over 9,000 lines detailing how to hook up to and check out my Inet-Access FAQ, over 9,000 lines detailing how to hook up to
the net and how to make your Internet provider business succeed in these most the net and how to make your Internet provider business succeed in these most
interesting times.</para> interesting times.</para>
</sect1> </sect1>
<sect1 ID="Warning"> <sect1 ID="Warning">
<title>Warning</title> <title>Warning</title>
<para>Multi-Port serial cards, such as the BocaBoard, are all but dead. <para>Multi-Port serial cards, such as the BocaBoard, are all but dead.
If you are in business as an Internet Service Provider (ISP), you will not want If you are in business as an Internet Service Provider (ISP), you will not want
to use any of these devices, because the new 56k modem standards will not to use any of these devices, because the new 56k modem standards will not
support them. Instead, you need digital modem/terminal server combinations such support them. Instead, you need digital modem/terminal server combinations such
as the Livingston PM3 &trade; , Cisco 5200 &trade; or US Robotics Total as the Livingston PM3 &trade; , Cisco 5200 &trade; or US Robotics Total
Control &trade;. Otherwise, you simply won't be competitive in major markets. Control &trade;. Otherwise, you simply won't be competitive in major markets.
Users want high speeds; you won't be able to provide them with a BocaBoard or Users want high speeds; you won't be able to provide them with a BocaBoard or
other multi-port serial card.</para> other multi-port serial card.</para>
<para>Even as a multi-port serial card, the BocaBoard is hopelessly <para>Even as a multi-port serial card, the BocaBoard is hopelessly
obsolete. The overwhelming majority of people who want to buy a BocaBoard would obsolete. The overwhelming majority of people who want to buy a BocaBoard would
be better off getting a accelerated card such as the Cyclades&trade; or be better off getting a accelerated card such as the Cyclades&trade; or
Rocketport&trade;. (When last I looked, Rocketport&trade; was a better board, Rocketport&trade;. (When last I looked, Rocketport&trade; was a better board,
but Cyclades&trade; had the most stable kernel support). Accelerated cards use but Cyclades&trade; had the most stable kernel support). Accelerated cards use
less of the CPU of your machine, and so you can support more ports per computer less of the CPU of your machine, and so you can support more ports per computer
with less performance degradation.</para> with less performance degradation.</para>
<para>That being said, perhaps you own one of these devices and want to <para>That being said, perhaps you own one of these devices and want to
make use of it, or perhaps you are planning an ISP based on a low-cost business make use of it, or perhaps you are planning an ISP based on a low-cost business
model that basically means the use of cast-off equipment from others. In that model that basically means the use of cast-off equipment from others. In that
case, the information in this document should be useful for you. But again, I case, the information in this document should be useful for you. But again, I
repeat: The person who buys a new BocaBoard at this point probably needs a few repeat: The person who buys a new BocaBoard at this point probably needs a few
more clues before starting his ISP or other venture.</para> more clues before starting his ISP or other venture.</para>
</sect1> </sect1>
<sect1 ID="RequiredMaterials"> <sect1 ID="RequiredMaterials">
<title>What do you need to install a BocaBoard?</title> <title>What do you need to install a BocaBoard?</title>
<orderedlist> <orderedlist>
<listitem> <listitem>
<para>The board itself and its manuals</para> <para>The board itself and its manuals</para>
</listitem> </listitem>
<listitem> <listitem>
<para>Your Linux source tree </para> <para>Your Linux source tree </para>
</listitem> </listitem>
<listitem> <listitem>
<para>Patience</para> <para>Patience</para>
</listitem> </listitem>
</orderedlist> </orderedlist>
</sect1> </sect1>
<sect1 ID="Procedure"> <sect1 ID="Procedure">
<title>The Basic Procedure</title> <title>The Basic Procedure</title>
<sect2 ID="RecompilingKernel"> <sect2 ID="RecompilingKernel">
<title>Recompiling the Kernel</title> <title>Recompiling the Kernel</title>
<para>The first step is to change your kernel so that it knows you <para>The first step is to change your kernel so that it knows you
have a BocaBoard. Unfortunately, this is not a part of the configure script; have a BocaBoard. Unfortunately, this is not a part of the configure script;
you must go in and modify the source by hand. In the older versions of the you must go in and modify the source by hand. In the older versions of the
kernel, this consists of putting the following line at the beginning of kernel, this consists of putting the following line at the beginning of
<filename>linux/drivers/char/serial.c</filename>:</para> <filename>linux/drivers/char/serial.c</filename>:</para>
<programlisting> #define CONFIG_BOCA 1</programlisting> <programlisting> #define CONFIG_BOCA 1</programlisting>
<para>As of some kernel version or another, this has changed. To make <para>As of some kernel version or another, this has changed. To make
it work with newer kernels, search for the it work with newer kernels, search for the
<programlisting>"BOCA_FLAGS" #define</programlisting> in <programlisting>"BOCA_FLAGS" #define</programlisting> in
<filename>serial.c</filename>, and change the value to</para> <filename>serial.c</filename>, and change the value to</para>
<programlisting>#define BOCA_FLAGS ASYNC_BOOT_AUTOCONF <programlisting>#define BOCA_FLAGS ASYNC_BOOT_AUTOCONF
</programlisting> </programlisting>
<para>You can then recompile your kernel using the instructions <para>You can then recompile your kernel using the instructions
included with the source tree. I recommend running the new kernel from a floppy included with the source tree. I recommend running the new kernel from a floppy
until you're very sure it works; otherwise, the procedure for getting back your until you're very sure it works; otherwise, the procedure for getting back your
system is mind-numbing at best.</para> system is mind-numbing at best.</para>
<para>At least to me, digging into my kernel and re-compiling it was <para>At least to me, digging into my kernel and re-compiling it was
quite a stressful venture! Relax; as long as you copy it to a floppy, your new quite a stressful venture! Relax; as long as you copy it to a floppy, your new
kernel is completely harmless. It won't bite! Honest! :-)</para> kernel is completely harmless. It won't bite! Honest! :-)</para>
</sect2> </sect2>
<sect2 ID="InstallingCard"> <sect2 ID="InstallingCard">
<title>Installing the Card</title> <title>Installing the Card</title>
<para>The default address on both the card and the Linux software for <para>The default address on both the card and the Linux software for
the configuration is 0x100; leave that alone. Set the IRQ on the card to Linux the configuration is 0x100; leave that alone. Set the IRQ on the card to Linux
default of 12. If you want to change the IRQ, you will have to search for default of 12. If you want to change the IRQ, you will have to search for
"BOCA_FLAGS" in the file. You will find lines like this:</para> "BOCA_FLAGS" in the file. You will find lines like this:</para>
<programlisting> { BASE_BAUD, 0x100, 12, BOCA_FLAGS }, /* ttyS16 <programlisting> { BASE_BAUD, 0x100, 12, BOCA_FLAGS }, /* ttyS16
*/ */
{ BASE_BAUD, 0x108, 12, BOCA_FLAGS }, /* ttyS17 { BASE_BAUD, 0x108, 12, BOCA_FLAGS }, /* ttyS17
*/</programlisting> */</programlisting>
<para>You can change the IRQ from 12 by changing the 12 to any valid <para>You can change the IRQ from 12 by changing the 12 to any valid
IRQ. I have not tried this, however.</para> IRQ. I have not tried this, however.</para>
</sect2> </sect2>
<sect2 ID="TellingLinux"> <sect2 ID="TellingLinux">
<title>Telling Linux about Your Card</title> <title>Telling Linux about Your Card</title>
<para>Once you have compiled your new kernel, switch off the machine <para>Once you have compiled your new kernel, switch off the machine
and install the card. Then, turn your machine on with the new kernel floppy in and install the card. Then, turn your machine on with the new kernel floppy in
the drive. If the installation succeeded, you should see all sorts of strange the drive. If the installation succeeded, you should see all sorts of strange
stuff about 16550 UARTS being connected to ttyS16-ttyS32. The system will then stuff about 16550 UARTS being connected to ttyS16-ttyS32. The system will then
come up normally.</para> come up normally.</para>
<para>The odds are pretty good that you don't actually have entries in <para>The odds are pretty good that you don't actually have entries in
<filename class='directory'>/dev </filename>for those lines. Remember that they start at 16 and go on to 32. If you <filename class='directory'>/dev </filename>for those lines. Remember that they start at 16 and go on to 32. If you
look at the source code, you'll see why; support for other cards is included in look at the source code, you'll see why; support for other cards is included in
the code for lower line numbers. Creating them is pretty simple, once you know the code for lower line numbers. Creating them is pretty simple, once you know
the trick. </para> the trick. </para>
<para>To create entries for dial-out lines (where you call out), type: <para>To create entries for dial-out lines (where you call out), type:
<screen>#mknod /dev/cuaxx c 4 N</screen></para> <screen>#mknod /dev/cuaxx c 4 N</screen></para>
<para>n = 64 + {line number}. The C indicates that this is a character <para>n = 64 + {line number}. The C indicates that this is a character
mode device. For example, to create the first couple of lines on your board, mode device. For example, to create the first couple of lines on your board,
type: type:
<screen>#mknod /dev/cua16 c 4 80 <screen>#mknod /dev/cua16 c 4 80
#mknod /dev/cua17 c 4 81</screen></para> #mknod /dev/cua17 c 4 81</screen></para>
<para>To create dial-in lines (where users call you), type:</para> <para>To create dial-in lines (where users call you), type:</para>
<screen>#mknod /dev/ttySxx c 5 n</screen> <screen>#mknod /dev/ttySxx c 5 n</screen>
<para>where N is the same as described above. For example, to create <para>where N is the same as described above. For example, to create
the first couple of lines on your BocaBoard, type:</para> the first couple of lines on your BocaBoard, type:</para>
<screen>#mknod /dev/ttyS16 c 5 80 <screen>#mknod /dev/ttyS16 c 5 80
#mknod /dev/ttyS17 c 5 81</screen> #mknod /dev/ttyS17 c 5 81</screen>
<para>It is recommended that you create both dial in and dial out <para>It is recommended that you create both dial in and dial out
lines for each port, so that you have maximum flexibility. It turns out to be lines for each port, so that you have maximum flexibility. It turns out to be
very handy to call another line of your system by activating one of your lines very handy to call another line of your system by activating one of your lines
as dial-out and calling your main number. I've done this already and it works as dial-out and calling your main number. I've done this already and it works
great! It's most useful for checking how things look "on the other side of the great! It's most useful for checking how things look "on the other side of the
fence"; I used it to find out how my software looked at 2400bps. (It's slower fence"; I used it to find out how my software looked at 2400bps. (It's slower
than the Linux console. A LOT slower, in fact).</para> than the Linux console. A LOT slower, in fact).</para>
<para>Once you've finished with this, you can add entries to your <para>Once you've finished with this, you can add entries to your
<filename>inittab</filename> file in the same way as you would for a standard ttySx entry, and the <filename>inittab</filename> file in the same way as you would for a standard ttySx entry, and the
modems or terminals should come up!</para> modems or terminals should come up!</para>
</sect2> </sect2>
</sect1> </sect1>
<sect1 ID="Problems"> <sect1 ID="Problems">
<title>Possible Problems</title> <title>Possible Problems</title>
<para>If you have problems, you may find that this is due to conflicts <para>If you have problems, you may find that this is due to conflicts
between your BocaBoard and systems with dual IDE controllers. According to between your BocaBoard and systems with dual IDE controllers. According to
Kevin Traas:</para> Kevin Traas:</para>
<blockquote> <blockquote>
<para>Is the kernel recognising the board? (i.e. Right at the start of <para>Is the kernel recognising the board? (i.e. Right at the start of
the boot process, all sixteen ports should be listed on screen with ttySxx, I/O the boot process, all sixteen ports should be listed on screen with ttySxx, I/O
Port, and IRQ identified.) Also, Port, and IRQ identified.) Also,
<command>setserial -bg ttyS*</command> should list *every* port in <command>setserial -bg ttyS*</command> should list *every* port in
your system.</para> your system.</para>
<para>By default, the BB2016 is configured to use IO Ports between <para>By default, the BB2016 is configured to use IO Ports between
0100 and 017f. This creates problems on systems with two IDE controllers. The 0100 and 017f. This creates problems on systems with two IDE controllers. The
second controller, ide1, uses 0170-0177 which falls into this range. Big second controller, ide1, uses 0170-0177 which falls into this range. Big
problems!!!</para> problems!!!</para>
<para>So, the solution, in my cases, is to go with an IO base of 0200 <para>So, the solution, in my cases, is to go with an IO base of 0200
through 027f. I haven't had any conflicts in this region; however, you may want through 027f. I haven't had any conflicts in this region; however, you may want
to check you system to be sure. (run to check you system to be sure. (run
<command>cat /proc/ioports</command> - better run <command>cat /proc/ioports</command> - better run
<command>cat /proc/interrupts</command> to make sure IRQ 12 isn't <command>cat /proc/interrupts</command> to make sure IRQ 12 isn't
used either.)</para> used either.)</para>
<para>Once you've found an IO range and IRQ that isn't used, you'll <para>Once you've found an IO range and IRQ that isn't used, you'll
have to change the jumpers on the BB2016 and edit have to change the jumpers on the BB2016 and edit
<filename>/usr/src/linux/drivers/char/serial.c</filename> to reflect the new <filename>/usr/src/linux/drivers/char/serial.c</filename> to reflect the new
settings. Then, compile the kernel and install as per normal.</para> settings. Then, compile the kernel and install as per normal.</para>
</blockquote> </blockquote>
<sect2 ID="AdditionalInfo"> <sect2 ID="AdditionalInfo">
<title>Additional Information and Service Comments</title> <title>Additional Information and Service Comments</title>
<para> If you want to use your new Boca card with any standard DB-25 <para> If you want to use your new Boca card with any standard DB-25
RS232 connector, you will have to get a special breakout box, which costs about RS232 connector, you will have to get a special breakout box, which costs about
$80. The card itself comes with a breakout box that plugs into the card through $80. The card itself comes with a breakout box that plugs into the card through
a truly formidable cable. It then supplies phone-like cables for the ports. The a truly formidable cable. It then supplies phone-like cables for the ports. The
special $80 box has phone-like cables that plug into the breakout box included special $80 box has phone-like cables that plug into the breakout box included
with the Boca card; you can then plug your modems or terminals into standard with the Boca card; you can then plug your modems or terminals into standard
RS-232 connectors on the box. Unless you actually have a system that accepts RS-232 connectors on the box. Unless you actually have a system that accepts
the phone-like connectors, you should add the price of the box to the cost of the phone-like connectors, you should add the price of the box to the cost of
the card when comparing it to other alternatives.</para> the card when comparing it to other alternatives.</para>
<para>I got my Boca 2016 card through a special wholesale deal that I <para>I got my Boca 2016 card through a special wholesale deal that I
don't think many people will be able to reproduce. It was available quickly. don't think many people will be able to reproduce. It was available quickly.
However, the breakout box for RS-232 took about two weeks to ship. You should However, the breakout box for RS-232 took about two weeks to ship. You should
be aware of your need for this box before you acquire the card. The 2016 board be aware of your need for this box before you acquire the card. The 2016 board
was $235 and the additional box was $79.95.</para> was $235 and the additional box was $79.95.</para>
<para>I've heard that this breakout box is no longer available, and <para>I've heard that this breakout box is no longer available, and
that now people just have special cables made. I'm not sure how you would go that now people just have special cables made. I'm not sure how you would go
about doing this, though.</para> about doing this, though.</para>
<para>Only one port of my first Boca 2016 worked. I called Boca, <para>Only one port of my first Boca 2016 worked. I called Boca,
expecting to hear a long string of questions and advice. When they said, expecting to hear a long string of questions and advice. When they said,
"Linux? What's that?" I feared the worst. However, upon hearing my actual "Linux? What's that?" I feared the worst. However, upon hearing my actual
problem, they cheerfully told me that the card was defective and I should send problem, they cheerfully told me that the card was defective and I should send
it back; full 5-year factory warranty, 30-days exchange. I was struck by how it back; full 5-year factory warranty, 30-days exchange. I was struck by how
cheery the lady was. It was as though they were expecting the worst, and very cheery the lady was. It was as though they were expecting the worst, and very
kindly making the most of it!</para> kindly making the most of it!</para>
<para>I had my hardware guy exchange the card. Unfortunately, the <para>I had my hardware guy exchange the card. Unfortunately, the
cards were back-ordered and they took about two more weeks to give me my new cards were back-ordered and they took about two more weeks to give me my new
card. I have to say that I was quite annoyed at this, since I was anxiously card. I have to say that I was quite annoyed at this, since I was anxiously
chomping at the bit to get this thing up and running. </para> chomping at the bit to get this thing up and running. </para>
<para>Some people have problems with ports past the first eight. I <para>Some people have problems with ports past the first eight. I
have tested my card up to port 11 and all the ports appear to be working. Boca have tested my card up to port 11 and all the ports appear to be working. Boca
Research quality control may be lacking; I would recommend that people with Research quality control may be lacking; I would recommend that people with
troubles with the card call Boca and deal with them directly. I suspect that if troubles with the card call Boca and deal with them directly. I suspect that if
I'd exchanged the card directly through the factory I would have had better I'd exchanged the card directly through the factory I would have had better
service than through my dealer. The factory people were all quite nice and service than through my dealer. The factory people were all quite nice and
eager to please.</para> eager to please.</para>
<para>Right now, I have only four phone lines. I bought the 16-port <para>Right now, I have only four phone lines. I bought the 16-port
card for two reasons: because it has modem control (unlike the smaller ones), card for two reasons: because it has modem control (unlike the smaller ones),
and in anticipation of future expansion. </para> and in anticipation of future expansion. </para>
<para>Some additional information on this subject from Kevin Traas of <para>Some additional information on this subject from Kevin Traas of
Baan Business Systems&trade;: </para> Baan Business Systems&trade;: </para>
<blockquote> <blockquote>
<para>BTW, I've used the BB2016 several times and found them to work <para>BTW, I've used the BB2016 several times and found them to work
really well under Linux. I'm extremely happy with them. They perform very well, really well under Linux. I'm extremely happy with them. They perform very well,
are very inexpensive, and are reliable. They claim 115200 bps per port. I've are very inexpensive, and are reliable. They claim 115200 bps per port. I've
got a unique situation whereby I've got two systems with a PPP serial link got a unique situation whereby I've got two systems with a PPP serial link
between them. I'm running this link at 115200 and I experience almost 0% error between them. I'm running this link at 115200 and I experience almost 0% error
rate (with hundreds of thousands of packets transmitted). My next step is to rate (with hundreds of thousands of packets transmitted). My next step is to
implement EQL and additional PPP links between the boxes to increase the implement EQL and additional PPP links between the boxes to increase the
bandwidth. We'll see how it goes.</para> bandwidth. We'll see how it goes.</para>
<para>One final note. Contrary to the suggestion in the HOWTO, I <para>One final note. Contrary to the suggestion in the HOWTO, I
build my own cables for the BB2016 (they've got RJ ports on them). At first, I build my own cables for the BB2016 (they've got RJ ports on them). At first, I
"dabbled" with RJ45-8 conductor plugs, but the BB2016 has RJ48-10 conductor "dabbled" with RJ45-8 conductor plugs, but the BB2016 has RJ48-10 conductor
jacks, so to get full modem support, I ended up going that route.</para> jacks, so to get full modem support, I ended up going that route.</para>
<para>I now run all 10 wires between the BB2016 and my modems. It <para>I now run all 10 wires between the BB2016 and my modems. It
works great! No problems, no regrets! The only initial problem I had was works great! No problems, no regrets! The only initial problem I had was
finding a source for RJ48 plugs, 10 conductor wire, and RJ48 to DB25 finding a source for RJ48 plugs, 10 conductor wire, and RJ48 to DB25
adapters. None of these are very cheap due to the low demand. Oh, yeah, and adapters. None of these are very cheap due to the low demand. Oh, yeah, and
you need an RJ48 crimper as well.</para> you need an RJ48 crimper as well.</para>
<para>If you want, I can build these cables for you and send them <para>If you want, I can build these cables for you and send them
to you. If you're interested, e-mail me and I'll let you know pricing, etc. I to you. If you're interested, e-mail me and I'll let you know pricing, etc. I
found building my own was cheaper than the adapter that is mentioned in the found building my own was cheaper than the adapter that is mentioned in the
HOWTO - which I couldn't find a source for anyway.</para> HOWTO - which I couldn't find a source for anyway.</para>
</blockquote> </blockquote>
<para>I believe the adapter mentioned in this document is no longer <para>I believe the adapter mentioned in this document is no longer
being manufacturered, leaving cables such as your own the only remaining way of being manufacturered, leaving cables such as your own the only remaining way of
connecting the device.</para> connecting the device.</para>
</sect2> </sect2>
</sect1> </sect1>
<sect1 ID="Acknowledgements"> <sect1 ID="Acknowledgements">
<title>Acknowledgements</title> <title>Acknowledgements</title>
<para>Kevin Traas has issued a helpful update to this FAQ that contains a <para>Kevin Traas has issued a helpful update to this FAQ that contains a
major correction to the information on major correction to the information on
<command>mknod</command>. He is also standing in as a new source for <command>mknod</command>. He is also standing in as a new source for
cables for the device.</para> cables for the device.</para>
<para>The information here was obtained by begging many people for help. <para>The information here was obtained by begging many people for help.
Unfortunately, I have forgotten their names due to a pressing need for disk Unfortunately, I have forgotten their names due to a pressing need for disk
space on my Netcom account. :-( Nonetheless, I thank them very much for their space on my Netcom account. :-( Nonetheless, I thank them very much for their
assistance when things looked blackest. This is my way of paying some of that assistance when things looked blackest. This is my way of paying some of that
back.</para> back.</para>
</sect1> </sect1>
</article> </article>

234
LDP/howto/docbook/DocBook-Install.sgml
View File

@ -18,8 +18,8 @@
<revhistory> <revhistory>
<revision> <revision>
<revnumber>v1.2</revnumber> <revnumber>v1.4</revnumber>
<date>2001-01-03</date> <date>2001-01-18</date>
<authorinitials>rbe</authorinitials> <authorinitials>rbe</authorinitials>
</revision> </revision>
</revhistory> </revhistory>
@ -470,7 +470,7 @@ In this section, we will locate and download the software on the Internet.
cp -r config config-temp cp -r config config-temp
cd config-temp cd config-temp
tex -ini -progname=hugelatex tex.ini tex -ini -progname=hugelatex tex.ini
mv latex.fmt hugelatex.fmt mv tex.fmt hugelatex.fmt
mv hugelatex.fmt /usr/share/texmf/web2c mv hugelatex.fmt /usr/share/texmf/web2c
cd .. cd ..
rm -r config-temp rm -r config-temp
@ -558,7 +558,7 @@ In this section, we will locate and download the software on the Internet.
</screen> </screen>
This Makefile uses hugelatex, so hugelatex must have been This Makefile uses hugelatex, so hugelatex must have been
setup already. When tex is run as hugelatex, jadetex, or setup already. When tex is run as hugelatex, jadetex, or
pdfjadetex, is gets it's program name (context) from argv[0] pdfjadetex, it gets its program name (context) from argv[0]
in the environment. Then, it scans texmf.cnf, and uses in the environment. Then, it scans texmf.cnf, and uses
any context-specific settings it finds. The format (.fmt) any context-specific settings it finds. The format (.fmt)
files in /usr/share/texmf/web2c are also loaded based on files in /usr/share/texmf/web2c are also loaded based on
@ -657,7 +657,7 @@ In this section, we will locate and download the software on the Internet.
<title>sgmltools-lite</title> <title>sgmltools-lite</title>
<para> <para>
If you like it, you can install the sgmltools-lite, but it is optional. If you like it, you can install the sgmltools-lite, but it is optional.
It's installation is the standard: Its installation is the standard:
<screen> <screen>
cd /usr/src cd /usr/src
tar -xvzf ~/sgmltools-lite-3.0.2.tar.gz tar -xvzf ~/sgmltools-lite-3.0.2.tar.gz
@ -672,150 +672,67 @@ In this section, we will locate and download the software on the Internet.
<para> <para>
One tweak that has to be done to make the sgmltools script work, is One tweak that has to be done to make the sgmltools script work, is
you have have to edit it and set the path to openjade: you have have to edit it and set the path to openjade:
vi `which sgmltools`. Consult it's docs to learn more about it. vi `which sgmltools`. Consult its docs to learn more about it.
</para> </para>
</sect2> </sect2>
<sect2> <sect2>
<title>htmldoc</title> <title>htmldoc</title>
<sect3>
<title>binary</title>
<para> <para>
Preferrably you downloaded a binary distribution of htmldoc for Preferrably you downloaded a binary distribution of htmldoc for
your platform. The installation is straightforward: just unpack it your platform. The installation is straightforward: just unpack it
and run the setup. Read the docs in the package for more info. and run the setup. Read the docs in the package for more info.
</para> </para>
</sect3>
<sect3>
<title>source</title>
<para> <para>
If you downloaded the source, installation is autoconf style. If you downloaded the source, you will also need the Fast Light Tool Kit
or else it will not link:
</para>
<para>
<ulink url="http://www.fltk.org/">http://www.fltk.org/</ulink>
</para>
<para>
Installation is autoconf style.
Just run the configure script, make, make install. If all goes Just run the configure script, make, make install. If all goes
well, it will install in /usr/bin. well, it will install in /usr/bin.
</para> </para>
</sect3>
<sect3>
<title>lpd_print</title>
<para> <para>
When generating pdf and ps files from html using htmldoc, it is The htmldoc program has a few glitches when generating output from
desireable to suppress generation of the header-navigation and html files from openjade. For instance, bullet items are not
footer-navigation links that are at the top and bottom of every rendered properly and shaded areas are not always shaded.
html page. These navigation features look ugly in this
case. To suppress them, a custom dsl stylesheet file is used.
</para> </para>
<para> <para>
The stylesheet below also directs openjade to output everything as To fix this problem, a perl script
one chunck of data to standard out. This output is piped to htmldoc. (<ulink url="http://www.linuxdoc.org/authors/tools/ldp_print.tar.gz">lpd_print</ulink>)
is available from <ulink url="http://www.linuxdoc.org/">LinuxDoc.org</ulink>.
The script processes a nochunks html file from openjade and then runs htmldoc on it
to produce correctly rendered pdf and ps.
<tip><para>Get it!</para></tip>
</para> </para>
<para> <para>
<Figure> <screen>
<title>htmldoc.dsl - custom DSSSL DocBook stylesheet</title> tar -xvzf ldp_print.tar.gz
<ProgramListing> cd ldp_print
&lt;!DOCTYPE style-sheet PUBLIC &quot;-//James Clark//DTD DSSSL Style Sheet//EN&quot; [ cp fix_print_html.lib /usr/lib/perl5/site_perl
&lt;!ENTITY % html &quot;IGNORE&quot;&gt; -- copy the lib somewhere where perl looks
&lt;![%html;[ cp ldp_print /usr/local/bin
&lt;!ENTITY % print &quot;IGNORE&quot;&gt; </screen>
&lt;!ENTITY docbook.dsl SYSTEM &quot;docbook.dsl&quot; CDATA dsssl&gt; Take a look at the script in case there are lines in it you need
]]&gt; to change for your system. Perhaps someday htmldoc's bugs will
&lt;!ENTITY % print &quot;INCLUDE&quot;&gt; be fixed and this script will not be needed anymore.
&lt;![%print;[
&lt;!ENTITY docbook.dsl SYSTEM &quot;docbook.dsl&quot; CDATA dsssl&gt;
]]&gt;
]&gt;
&lt;style-sheet&gt;
&lt;style-specification id=&quot;htmldoc&quot; use=&quot;docbook&quot;&gt;
&lt;style-specification-body&gt;
(declare-characteristic preserve-sdata?
;; this is necessary because right now jadetex does not understand
;; symbolic entities, whereas things work well with numeric entities.
&quot;UNREGISTERED::James Clark//Characteristic::preserve-sdata?&quot;
#f)
(define %header-navigation%
;; Should navigation links be added to the top of each page?
#f)
(define %footer-navigation%
;; Should navigation links be added to the bottom of each page?
#f)
(define %generate-legalnotice-link%
;; put the legal notice in a separate file
#t)
(define %admon-graphics-path%
;; use graphics in admonitions, set their
&quot;../images/&quot;)
(define %admon-graphics%
#f)
(define %funcsynopsis-decoration%
;; make funcsynopsis look pretty
#t)
(define nochunks
;; dont make multiple files, output all to stdout
#t)
(define %root-filename%
;; The filename of the root HTML document (e.g, &quot;index&quot;).
&quot;index&quot;)
(define %html-ext%
;; Default extension for HTML output files
&quot;.htm&quot;)
(define %generate-article-toc%
;; Should a Table of Contents be produced for Articles?
;; If true, a Table of Contents will be generated for each 'Article'.
#t)
(define %generate-part-toc%
#f)
(define %generate-article-titlepage%
#t)
(define (chunk-skip-first-element-list)
;; forces the Table of Contents on separate page
'())
(define %shade-verbatim%
#t)
(define %use-id-as-filename%
;; Use ID attributes as name for component HTML files?
#f)
(define %graphic-default-extension%
&quot;gif&quot;)
(define %section-autolabel%
;; For enumerated sections (1.1, 1.1.1, 1.2, etc.)
#t)
(define (toc-depth nd)
;; more depth, 2 levels, to toc, instead of flat hierarchy
2)
&lt;/style-specification-body&gt;
&lt;/style-specification&gt;
&lt;external-specification id=&quot;docbook&quot; document=&quot;docbook.dsl&quot;&gt;
&lt;/style-sheet&gt;
</ProgramListing>
</Figure>
This file can be downloaded at the link below:
</para>
<para>
<ulink url="http://www.comptechnews.com/~reaster/htmldoc.dsl">http://www.comptechnews.com/~reaster/htmldoc.dsl</ulink>
</para>
<para>
Install the file to the same place where ldp.dsl is installed: in the
html/ directory of the Modular DocBook Stylesheets, which was installed
at /usr/local/share/sgml/dsssl/docbook in Section 3.3 above.
</para> </para>
</sect3>
</sect2> </sect2>
@ -929,7 +846,7 @@ export JADE_HOME SGML_SHARE PATH SGML_CATALOG_FILES
<title>Using DocBook</title> <title>Using DocBook</title>
<para> <para>
Now that everything is installed, it's time to test it out Now that everything is installed, it's time to test it out
and see how to use openjade and sgmltools. and see how to use openjade and the other tools.
</para> </para>
<para> <para>
@ -1311,14 +1228,16 @@ bash$
<Screen> <Screen>
bash$ ls -l bash$ ls -l
-rw-r--r-- 1 reaster users 1143 Dec 31 18:18 test.sgml -rw-r--r-- 1 reaster users 1143 Dec 31 18:18 test.sgml
bash$ openjade -t sgml -d $SGML_SHARE/dsssl/docbook/html/htmldoc.dsl test.sgml | htmldoc -f test-htmldoc.ps - bash$ export DSL_HTML=$SGML_SHARE/dsssl/docbook/html/ldp.dsl\#html
bash$ openjade -t sgml -V nochunks -d $DSL_HTML test.sgml | htmldoc -f test-htmldoc.ps -
bash$ ls -l bash$ ls -l
-rw-r--r-- 1 reaster users 9050 Jan 1 00:44 test-htmldoc.ps -rw-r--r-- 1 reaster users 9050 Jan 1 00:44 test-htmldoc.ps
-rw-r--r-- 1 reaster users 1143 Dec 31 18:18 test.sgml -rw-r--r-- 1 reaster users 1143 Dec 31 18:18 test.sgml
bash$ bash$
</Screen> </Screen>
</figure> </figure>
Notice the use of htmldoc.dsl, the customized dsssl stylesheet for this task. If the ps doesn't appear as expected, it is due to bugs in htmldoc.
Look inside the ldp_print script if you want to use it to make ps.
</para> </para>
</sect2> </sect2>
@ -1369,8 +1288,14 @@ total 128
-rw-r--r-- 1 reaster users 1143 Dec 31 18:18 test.sgml -rw-r--r-- 1 reaster users 1143 Dec 31 18:18 test.sgml
-rw-r--r-- 1 reaster users 18719 Dec 31 20:51 test.tex -rw-r--r-- 1 reaster users 18719 Dec 31 20:51 test.tex
bash$ bash$
bash$ pdfjadetex test.tex
[snip]
bash$ pdfjadetex test.tex
[snip]
</screen> </screen>
</figure> </figure>
Pdfjadetex must be run up to three times to resolve all
internal references for things such as TOC page numbers.
</para> </para>
<para> <para>
@ -1379,16 +1304,17 @@ bash$
<Screen> <Screen>
bash$ ls -l bash$ ls -l
-rw-r--r-- 1 reaster users 1143 Dec 31 18:18 test.sgml -rw-r--r-- 1 reaster users 1143 Dec 31 18:18 test.sgml
bash$ openjade -t sgml -d $SGML_SHARE/dsssl/docbook/html/htmldoc.dsl test.sgml | htmldoc -f test-htmldoc.pdf - bash$ export DSL_HTML=$SGML_SHARE/dsssl/docbook/html/ldp.dsl\#html
bash$ openjade -t sgml -V nochunks -d $DSL_HTML test.sgml > test-htmldoc.htm
bash$ ldp_print test-htmldoc.htm
bash$ ls -l bash$ ls -l
-rw-r--r-- 1 reaster users 9050 Jan 1 01:17 test-htmldoc.pdf -rw-r--r-- 1 reaster users 9050 Jan 1 01:17 test-htmldoc.pdf
-rw-r--r-- 1 reaster users 1143 Dec 31 18:18 test.sgml -rw-r--r-- 1 reaster users 1143 Dec 31 18:18 test.sgml
bash$ bash$
</Screen> </Screen>
</figure> </figure>
This is nearly the same command as used to generated a ps file with htmldoc but If enabled in the ldp_print script, this would generate a ps file
with just a different filename. Htmldoc understands what you want based on also.
the filename extension.
</para> </para>
</sect2> </sect2>
@ -1407,7 +1333,7 @@ bash$
<ProgramListing> <ProgramListing>
# Generates online and print versions of SGML source file. # Generates online and print versions of SGML source file.
BASENAME=DocBook-Install-mini-HOWTO BASENAME=DocBook-Install
# SGML source file. # SGML source file.
SGML_FILE=$(BASENAME).sgml SGML_FILE=$(BASENAME).sgml
@ -1415,10 +1341,10 @@ SGML_FILE=$(BASENAME).sgml
# Stylesheets # Stylesheets
DSL_PRINT=$(SGML_SHARE)/dsssl/docbook/print/ldp.dsl\#print DSL_PRINT=$(SGML_SHARE)/dsssl/docbook/print/ldp.dsl\#print
DSL_HTML=$(SGML_SHARE)/dsssl/docbook/html/ldp.dsl\#html DSL_HTML=$(SGML_SHARE)/dsssl/docbook/html/ldp.dsl\#html
DSL_HTMLDOC=$(SGML_SHARE)/dsssl/docbook/html/htmldoc.dsl
# Generated files. # Generated files.
HTML_FILE=index.html HTML_FILE=index.html
HTM_FILE=$(BASENAME).htm
TEX_FILE=$(BASENAME).tex TEX_FILE=$(BASENAME).tex
RTF_FILE=$(BASENAME).rtf RTF_FILE=$(BASENAME).rtf
PDF_FILE=$(BASENAME).pdf PDF_FILE=$(BASENAME).pdf
@ -1430,6 +1356,8 @@ PS_FILE=$(BASENAME).ps
html: $(HTML_FILE) html: $(HTML_FILE)
htm: $(HTM_FILE)
tex: $(TEX_FILE) tex: $(TEX_FILE)
rtf: $(RTF_FILE) rtf: $(RTF_FILE)
@ -1440,10 +1368,10 @@ dvi: $(DVI_FILE)
ps: $(PS_FILE) ps: $(PS_FILE)
all: html tex rtf pdf dvi ps all: html htm tex rtf pdf dvi ps
clean: clean:
rm -f $(BASENAME).{log,aux,ps,pdf,tex,dvi,rtf,fot} rm -f $(BASENAME).{htm,log,aux,ps,pdf,tex,dvi,rtf,fot}
rm -f *.html rm -f *.html
distclean: clean distclean: clean
@ -1458,31 +1386,49 @@ dist: clean package
distall: all package distall: all package
# Compile rules. # Compile rules.
$(HTML_FILE): $(SGML_FILE) $(HTML_FILE): $(SGML_FILE)
openjade -t sgml -d $(DSL_HTML) $(SGML_FILE) openjade -t sgml -d $(DSL_HTML) $(SGML_FILE)
$(HTM_FILE): $(SGML_FILE)
openjade -t sgml -V nochunks -d $(DSL_HTML) \
$(SGML_FILE) > $(HTM_FILE)
$(TEX_FILE): $(SGML_FILE) $(TEX_FILE): $(SGML_FILE)
openjade -t tex -d $(DSL_PRINT) $(SGML_FILE) openjade -t tex -d $(DSL_PRINT) $(SGML_FILE)
$(RTF_FILE): $(SGML_FILE) $(RTF_FILE): $(SGML_FILE)
openjade -t rtf -d $(DSL_PRINT) $(SGML_FILE) openjade -t rtf -d $(DSL_PRINT) $(SGML_FILE)
# [pdf]jadetex is run 3 times to resolve references.
#$(PDF_FILE): $(TEX_FILE) #$(PDF_FILE): $(TEX_FILE)
# pdfjadetex $(TEX_FILE) # pdfjadetex $(TEX_FILE)
# pdfjadetex $(TEX_FILE)
# pdfjadetex $(TEX_FILE)
$(PDF_FILE): $(SGML_FILE) # This *should* work, but htmldoc has bugs ...
openjade -t sgml -d $(DSL_HTMLDOC) $(SGML_FILE) | htmldoc -f $(PDF_FILE) - #$(PDF_FILE): $(SGML_FILE)
# openjade -t sgml -V nochunks -d $(DSL_HTML) \
# $(SGML_FILE) | htmldoc -f $(PDF_FILE) -
# Have to use ldp_print to work around htmldoc bugs
# ldp_print can also do the ps file - see script
$(PDF_FILE): $(HTM_FILE)
ldp_print $(HTM_FILE)
$(DVI_FILE): $(TEX_FILE) $(DVI_FILE): $(TEX_FILE)
jadetex $(TEX_FILE) jadetex $(TEX_FILE)
jadetex $(TEX_FILE)
jadetex $(TEX_FILE)
$(PS_FILE): $(DVI_FILE) $(PS_FILE): $(DVI_FILE)
dvips $(DVI_FILE) dvips $(DVI_FILE)
#$(PS_FILE): $(SGML_FILE) #$(PS_FILE): $(SGML_FILE)
# openjade -t sgml -d $(DSL_HTMLDOC) $(SGML_FILE) | htmldoc -f $(PS_FILE) - # openjade -t sgml -V nochunks -d $(DSL_HTML) \
# $(SGML_FILE) | htmldoc -f $(PS_FILE) -
</ProgramListing> </ProgramListing>
</Figure> </Figure>
@ -1671,7 +1617,7 @@ DESCRIPTION
foo does nothing useful. foo does nothing useful.
OPTIONS OPTIONS
-f bar Takes bar as it's run control file. If this were a -f bar Takes bar as its run control file. If this were a
real program, there might be more to say here about real program, there might be more to say here about
what bar is and how it will be used. what bar is and how it will be used.
@ -1797,7 +1743,7 @@ bash$ less foo.1
</para> </para>
<para> <para>
<ulink url="http://www.comptechnews.com/~reaster/mini-HOWTO/DocBook-Install-mini-HOWTO/">http://www.comptechnews.com/~reaster/mini-HOWTO/DocBook-Install-mini-HOWTO/</ulink> <ulink url="http://www.linuxdoc.org/HOWTO/mini/DocBook-Install/">http://www.linuxdoc.org/HOWTO/mini/DocBook-Install/</ulink>
</para> </para>
</sect2> </sect2>

19
LDP/howto/docbook/Nvidia-OpenGL-Configuration.sgml
View File

@ -19,8 +19,8 @@
<revhistory> <revhistory>
<revision> <revision>
<revnumber>v1.5</revnumber> <revnumber>v1.6</revnumber>
<date>2001-01-14</date> <date>2001-01-17</date>
<authorinitials>rbe</authorinitials> <authorinitials>rbe</authorinitials>
</revision> </revision>
</revhistory> </revhistory>
@ -61,7 +61,7 @@
</para> </para>
<para> <para>
<ulink url="http://www.linuxdoc.org/HOWTO/mini/Nvidia-OpenGL-Configuration/">http://www.linuxdoc.org/HOWTO/mini/Nvidia-OpenGL-Configuration/</ulink> <ulink url="http://www.linuxdoc.org/HOWTO/mini/Nvidia-OpenGL-Configuration-mini-HOWTO/">http://www.linuxdoc.org/HOWTO/mini/Nvidia-OpenGL-Configuration-mini-HOWTO/</ulink>
</para> </para>
</sect2> </sect2>
@ -578,6 +578,19 @@
tar -xvzf NVIDIA_kernel-0.9-5.tar.gz tar -xvzf NVIDIA_kernel-0.9-5.tar.gz
tar -xvzf NVIDIA_GLX-0.9-5.tar.gz tar -xvzf NVIDIA_GLX-0.9-5.tar.gz
cd NVIDIA_kernel-0.9-5 cd NVIDIA_kernel-0.9-5
</screen>
<tip>
<para>
If you experience problems starting X, see the files
TNT_USERS_README and M64_USERS_README. These files
explain how to tweak the kernel driver. They were
written to fix problems with TNT and TNT2 M64 cards
but these tweaks are reported to help the GeForce2 MX
also. Try bypassing the BIOS as explained in
M64_USERS_README.
</para>
</tip>
<screen>
make make
cd .. cd ..
cd NVIDIA_GLX-0.9-5 cd NVIDIA_GLX-0.9-5