summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/jadetex/base/install.sgm
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/jadetex/base/install.sgm')
-rw-r--r--Master/texmf-dist/doc/jadetex/base/install.sgm474
1 files changed, 474 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/jadetex/base/install.sgm b/Master/texmf-dist/doc/jadetex/base/install.sgm
new file mode 100644
index 00000000000..9482522f99f
--- /dev/null
+++ b/Master/texmf-dist/doc/jadetex/base/install.sgm
@@ -0,0 +1,474 @@
+<!DOCTYPE Article PUBLIC "-//OASIS//DTD DocBook V3.1//EN"
+[ <!ENTITY last-update "2000-03-20 23:32 GMT">
+]>
+<Article>
+ <ArtHeader>
+ <Title>Installing JadeTeX</Title>
+ <Author>
+ <FirstName>Frank</FirstName>
+ <OtherName>Atanassow</OtherName>
+ <Surname>Christoph</Surname>
+ <Affiliation>
+ <OrgName>Next Solution Co., Ltd.</OrgName>
+ </Affiliation>
+ </Author>
+ <Author>
+ <FirstName>Sebastian</FirstName>
+ <OtherName>P Q</OtherName>
+ <Surname>Rahtz</Surname>
+ <Affiliation>
+ <OrgName>Oxford University Computing Services</OrgName>
+ </Affiliation>
+ </Author>
+ <Author>
+ <FirstName>Simon</FirstName>
+ <OtherName></OtherName>
+ <Surname>Pepping</Surname>
+ <Affiliation>
+ <OrgName>Elsevier Science B.V.</OrgName>
+ </Affiliation>
+ </Author>
+ <RevHistory>
+ <Revision>
+ <RevNumber>1</RevNumber>
+ <Date>1999/12/2</Date>
+ <AuthorInitials>FAC</AuthorInitials>
+ <RevRemark>Created.</RevRemark>
+ </Revision>
+ <Revision>
+ <RevNumber>2</RevNumber>
+ <Date>2000/03/20</Date>
+ <AuthorInitials>SR</AuthorInitials>
+ <RevRemark>Edited, folded in remarks of SP.</RevRemark>
+ </Revision>
+ </RevHistory>
+ </ArtHeader>
+
+ <Section>
+
+ <Title>Introduction</Title>
+
+ <Para>This documents is based on a note by FC describing his experience installing JadeTeX
+ with OpenJade 1.3 and teTeX 1.06 (on Unix). It has since been
+ expanded and checked by SR and SP. It is aimed to people who
+ have perhaps some experience using TeX and LaTeX, enough to write up
+ technical reports using simple macros, but know little or nothing
+ about format files or the particulars of the TeX distribution
+ structure, and consequently have a rough time with
+ JadeTeX&#8230;</Para>
+<Para>This document relates to JadeTeX version 2.11 or later.</Para>
+
+ <Para>To use JadeTeX, you first of all should compile and install
+ OpenJade. The resulting <Command>openjade</Command> executable, used
+ with the <Option>-t tex</Option> flag, will format an
+ <Acronym>SGML/XML</Acronym> file and yield a TeX output file. Using
+ <Command>jadetex</Command> or <Command>pdfjadetex</Command>, you can
+ transform this into <Acronym>DVI</Acronym> or <Acronym>PDF</Acronym>;
+ from <Acronym>DVI</Acronym>, you can use a program like
+ <Command>dvips</Command> to get PostScript output. This note describes
+ how to build and install the former two programs,
+ <Command>jadetex</Command> and <Command>pdfjadetex</Command>.</Para>
+ </Section>
+
+ <Section>
+ <Title>Increasing TeX capacities</Title>
+
+ <Para>The TeX output file uses a macro package, JadeTeX, built
+ on top of LaTeX, just as
+ LaTeX is a macro package sitting on top of plain TeX. It is
+ probably possible to just stick an <Literal>\input</Literal> at the
+ top of your <Filename>.tex</Filename> file and use the JadeTeX macros
+ this way, but that would be slow since TeX would need to parse and
+ compile the macro definitions every time you format your
+ <Filename>.tex</Filename> file. So what we do instead is to use TeX
+ (actually, <Command>initex</Command>) to read in the LaTeX
+ format, followed by the JadeTeX package,
+ once, and dump the compiled image to what is called a <Quote>format
+ file.</Quote> This is the same way that LaTeX is usually employed.
+ Once the format file is built and installed, it is easy to arrange for
+ TeX to read it in quickly and automatically when you process a
+ <Filename>.tex</Filename> file.</Para>
+
+ <Para>But, as ever, there are complications, relating to TeX's capacity
+ restrictions. TeX is designed to use a fixed amount of
+ resources to process documents; for example, there is a maximum number
+ of strings that can be allocated, and a maximum stack size. If a
+ processing run exceeds the default limits, TeX will complain and refuse to
+ continue. Unfortunately, OpenJade's TeX backend tends to exceed these
+ default limits.</Para>
+
+ <Para>Fortunately, though, there is no need to recompile your TeX
+ binary. If you are using teTeX (or any other Web2c-based distribution)
+ there will be a file called <Filename>texmf.cnf</Filename> in your
+ installation which sets the capacity parameters and is consulted every
+ time TeX is run. By adding the right parameter settings here, you can
+ ensure that JadeTeX will be unlikely to run out of memory.</Para>
+
+ <Para>Where is <Filename>texmf.cnf</Filename>? You can find it in the
+ <Filename>web2c</Filename> directory under
+ your <Filename>texmf</Filename> tree... which begs the question, where
+ is <Filename>texmf</Filename>? The most
+ straightforward way to find it is to make sure all the TeX executables
+ are in your <EnVar>PATH</EnVar>; then do:
+
+ <Screen Format="linespecific"
+><Prompt>$</Prompt> <UserInput>kpsewhich -expand-var '$TEXMFMAIN'</UserInput>
+/usr/share/texmf/web2c/texmf.cnf</Screen>
+
+ and it will
+ respond with the location of your texmf tree. As you can see, it is also
+ known as <Replaceable>$TEXMFMAIN</Replaceable>, which is how I shall
+ refer to it in the sequel.</Para>
+
+ <Para> If for some reason <Command>kpsewhich</Command> is not in your
+ <EnVar>PATH</EnVar>,
+ and you don't know where it is, here are some likely locations:
+
+ <SimpleList>
+ <Member><Filename>/usr/share/texmf</Filename></Member>
+ <Member><Filename>/usr/local/share/texmf</Filename></Member>
+ <Member><Filename>/usr/local/teTeX/texmf</Filename></Member>
+ <Member><Filename>/usr/local/lib/teTeX/texmf</Filename></Member>
+ <Member><Filename>/usr/local/lib/texmf</Filename></Member>
+ <Member><Filename>/usr/lib/texmf</Filename></Member>
+ <Member><Filename>/usr/lib/teTeX/texmf</Filename></Member>
+ </SimpleList></Para>
+
+ <Para>In a minute we are going to modify <Filename>texmf.cnf</Filename> to
+ increase the capacities, then build the JadeTeX format file and install
+ the JadeTeX executable(s). But before we go further, check if you have
+ an executable named <Command>hugelatex</Command>:
+
+ <Screen Format="Linespecific"
+><Prompt>$</Prompt> <UserInput>which hugelatex</UserInput></Screen>
+
+ If you are using teTeX, the answer is: probably not.</Para>
+
+ <Para><Command>hugelatex</Command> is a version of latex with greater
+ capacity settings than the usual one, which is named simply
+ <Command>latex</Command>. You need to build your format file
+ using <Command>hugelatex</Command> rather than
+ <Command>latex</Command>, so that JadeTeX inherits the `huge' settings.
+ In addition, if you make any changes to the literate source of the
+ JadeTeX macro package (see below), a normal <Command>latex</Command>
+ will not do.</Para>
+
+ <Para>First we need to update texmf.cnf to ensure that
+ <Command>hugelatex</Command> really is
+ <Quote>huge</Quote>. First, make a backup:
+
+ <Screen Format="linespecific"
+><Prompt>$</Prompt> <UserInput>cp texmf.cnf texmf.cnf.orig</UserInput></Screen>
+
+ Then take a look at the top of the file. It will probably say:
+
+<ProgramListing Format="linespecific"
+>% original texmf.cnf -- runtime path configuration file for kpathsea.
+% (If you change or delete `original' on the previous line, the
+% distribution won't install its version over yours.)
+</ProgramListing>
+If it says
+<ProgramListing Format="linespecific"
+>% TeX Live texmf.cnf
+</ProgramListing>
+then you can skip all this and proceed to the next section, as TeX
+ Live is already set up for JadeTeX</Para>
+
+<Para>
+ If you have an `original', follow those directions and delete the string
+ <Literal>original</Literal> to ensure that
+ future upgrades won't obliterate your changes.</Para>
+
+ <Para>In the latter half of the file, you will find the capacity settings,
+ which look something like this:
+
+ <ProgramListing Format="linespecific"
+>pool_size = 125000
+pool_size.context = 750000</ProgramListing>
+
+ Here, <Literal>pool_size</Literal> is the name of the parameter in
+ both cases, but the second one is qualified with
+ <Literal>.context</Literal>, which indicates that this setting will be
+ preferred when using the ConTeXt macro package. We need to make similar
+ accomodations not only for <Command>hugelatex</Command> but also
+ <Command>jadetex</Command> and <Command>pdfjadetex</Command>.
+ Unfortunately, we don't know the minimal required values for every
+ parameter and some of these values are probably
+ ridiculously high, but no matter ...
+
+ <ProgramListing Format="linespecific"
+>% hugelatex settings
+main_memory.hugelatex = 1100000
+param_size.hugelatex = 1500
+stack_size.hugelatex = 1500
+hash_extra.hugelatex = 15000
+string_vacancies.hugelatex = 45000
+pool_free.hugelatex = 47500
+nest_size.hugelatex = 500
+save_size.hugelatex = 5000
+pool_size.hugelatex = 500000
+max_strings.hugelatex = 55000
+font_mem_size.hugelatex= 400000
+
+% jadetex & pdfjadetex
+main_memory.jadetex = 1500000
+param_size.jadetex = 1500
+stack_size.jadetex = 1500
+hash_extra.jadetex = 50000
+string_vacancies.jadetex = 45000
+pool_free.jadetex = 47500
+nest_size.jadetex = 500
+save_size.jadetex = 5000
+pool_size.jadetex = 500000
+max_strings.jadetex = 55000
+
+main_memory.pdfjadetex = 2500000
+param_size.pdfjadetex = 1500
+stack_size.pdfjadetex = 1500
+hash_extra.pdfjadetex = 50000
+string_vacancies.pdfjadetex = 45000
+pool_free.pdfjadetex = 47500
+nest_size.pdfjadetex = 500
+save_size.pdfjadetex = 5000
+pool_size.pdfjadetex = 500000
+max_strings.pdfjadetex = 55000
+</ProgramListing>
+
+ Add these to the end of the file, or wherever makes you happy.</Para>
+
+ <Para>Now let's build some format files. Under
+ <Filename><Replaceable>$TEXMFMAIN</Replaceable>/tex/latex/config</Filename>,
+ you will find the files necessary to rebuild <Command>latex</Command>.
+ Copy them somewhere temporary and go there:
+
+ <Screen Format="linespecific"
+><Prompt>$</Prompt> <UserInput>cp -R /usr/share/texmf/tex/latex/config /tmp</UserInput>
+<Prompt>$</Prompt> <UserInput>cd /tmp/config</UserInput></Screen>
+
+ Now do this:
+
+ <Screen Format="linespecific"
+><Prompt>$</Prompt> <UserInput>tex -ini -progname=hugelatex latex.ini</UserInput></Screen>
+
+ This will produce a file <Filename>latex.fmt</Filename>
+ in the same directory. Rename this to
+ <Filename>hugelatex.fmt</Filename>,
+ then become root and put it in
+ <Filename><Replaceable>$TEXMFMAIN</Replaceable>/web2c</Filename>. This
+ is where all the format files are kept. (You can delete the other copied
+ files from <Filename>config</Filename> afterwards.)
+
+ <Screen Format="linespecific"
+><Prompt>$</Prompt> <UserInput>mv hugelatex.fmt /usr/share/texmf/web2c</UserInput></Screen>
+ </Para>
+
+ <Para>Now just create a symbolic link from <Command>tex</Command> to
+ <Command>hugelatex</Command>:
+
+ <Screen Format="linespecific"
+><Prompt>$</Prompt> <UserInput>ln -s /usr/bin/tex /usr/local/bin/hugelatex</UserInput></Screen>
+
+ When <Command>tex</Command> is invoked, it looks at the name
+ <Replaceable>X</Replaceable> it was invoked with, then loads the format
+ file <Filename><Replaceable>X</Replaceable>.fmt</Filename> from
+ <Filename><Replaceable>$TEXMFMAIN</Replaceable>/web2c</Filename> before
+ it starts processing the document. So creating this symbolic link is all
+ that is needed to create the <Command>hugelatex</Command>
+ executable.</Para>
+ </Section>
+
+ <Section>
+ <Title>Creating the format files</Title>
+ <Para>Next, take a look at your OpenJade distribution. Under the directory
+ <Filename>dsssl</Filename> you will find the files necessary to build
+ jadetex and pdfjadetex, including a Makefile. If you don't have, and
+ neglected to build, a <Command>hugelatex</Command>, then you will first
+ need to edit the Makefile and replace <Command>hugelatex</Command> with
+ <Command>latex</Command>. Otherwise, become root and just do:
+
+ <Screen Format="linespecific"
+><Prompt>$</Prompt> <UserInput>make install</UserInput></Screen>
+
+ This creates <Filename>jadetex.fmt</Filename> and
+ <Filename>pdfjadetex.fmt</Filename>, puts them in
+ <Filename><Replaceable>$TEXMFMAIN</Replaceable>/web2c</Filename> for you
+ (using <Command>kpsewhich</Command> to find
+ <Replaceable>$TEXMFMAIN</Replaceable>), and installs a few other
+ auxiliary files under
+ <Filename><Replaceable>$TEXMFMAIN</Replaceable>/tex/jadetex</Filename>.</Para>
+ <Para>All that's left to do is to create the links:
+
+ <Screen Format="linespecific"
+><Prompt>$</Prompt> <UserInput>ln -s /usr/bin/tex /usr/bin/jadetex</UserInput>
+<Prompt>$</Prompt> <UserInput>ln -s /usr/bin/pdftex /usr/bin/pdfjadetex</UserInput></Screen>
+ (changing the location of the binary directory to wherever your TeX is)
+ and run <Command>mktexlsr</Command> so that your TeX distribution becomes
+ aware of the newly installed files in
+ <Filename><Replaceable>$TEXMFMAIN</Replaceable>/tex/jadetex.</Filename>
+
+ <Screen Format="linespecific"
+><Prompt>$</Prompt> <UserInput>mktexlsr</UserInput></Screen></Para>
+
+ </Section>
+
+ <Section>
+ <Title>Testing the installation</Title>
+ <Para>Finally, test your installation using the demonstration files in
+ that directory:
+
+ <Screen Format="linespecific"
+><Prompt>$</Prompt><UserInput> openjade -t tex -d demo.dsl demo.sgm</UserInput>
+<Prompt>$</Prompt> <UserInput>jadetex demo.tex</UserInput>
+<Prompt>$</Prompt> <UserInput>pdfjadetex demo.tex</UserInput></Screen>
+
+ You're done!</Para>
+ </Section>
+
+ <Section>
+ <Title>Frequently Asked Questions</Title>
+ <QandASet>
+ <QandAEntry>
+ <Question>
+ <Para>I installed JadeTeX, but when I run it, it complains that a
+ file named <Filename>unicode.sty</Filename> (or
+ <Filename>dsssl.def</Filename>, etc) can't be found. What did I do
+ wrong?</Para>
+ </Question>
+ <Answer>
+ <Para>You didn't run the <Command>mktexlsr</Command>, so
+ <Command>kpathsea</Command> doesn't know about the newly installed
+ files.</Para>
+ </Answer>
+ </QandAEntry>
+ <QandAEntry>
+ <Question>
+ <Para>I don't like JadeTeX's default behavior in some situations.
+ How do I modify it?</Para>
+ </Question>
+ <Answer>
+ <Para>If for some reason you want to modify the JadeTeX macro
+ package, modify the file <Filename>jadetex.dtx</Filename>. This is
+ the literate source for the format file and other files installed
+ under
+ <Filename><Replaceable>$TEXMFMAIN</Replaceable>/tex/jadetex</Filename>.</Para>
+ <Para>To format it, use <Command>hugelatex</Command>:
+
+ <Screen Format="linespecific"><Prompt>$</Prompt> <UserInput>hugelatex jadetex.dtx</UserInput></Screen>
+
+ You will get tons of overfull hboxes
+ but if you are
+ using <Command>hugelatex</Command> rather than <Command>latex</Command>,
+ it will work.</Para>
+
+ <Para>Formatting the batch file <Filename>jadetex.ins</Filename>
+ will produce stripped sources
+ (<Filename>dsssl.def</Filename> and
+ <Filename>jadetex.ltx</Filename>),
+ which can be compiled into format files as before:
+
+ <Screen Format="linespecific"
+><Prompt MoreInfo="None">$</Prompt> <UserInput MoreInfo="None">hugelatex jadetex.ins</UserInput>
+<Prompt>$</Prompt> <UserInput>make -f Makefile.jadetex</UserInput></Screen>
+ </Para>
+ </Answer>
+ </QandAEntry>
+
+ <QandAEntry>
+ <Question>
+ <Para>What fonts can I use?</Para>
+ </Question>
+ <Answer>
+ <Para>Following is the names of the font families supported at the
+ time of writing. Of course you must actually have these fonts
+ installed to format the document (but not to produce the TeX
+ output).</Para>
+ <SimpleList>
+ <Member>Arial</Member>
+ <Member>Helvetica</Member>
+ <Member>Palatino</Member>
+ <Member>Bookman</Member>
+ <Member>Courier</Member>
+ <Member>Symbol</Member>
+ <Member>Wingdings</Member>
+ <Member>WingDings</Member>
+ <Member>LucidaSans</Member>
+ <Member>LucidaBright</Member>
+ <Member>Savoy</Member>
+ <Member>ACaslon</Member>
+ <Member>Caslon</Member>
+ <Member>Formata</Member>
+ <Member>FranklinGothic</Member>
+ <Member>OCRAbyBT</Member>
+ <Member>AGaramond</Member>
+ <Member>Avant-Garde</Member>
+ <Member>Courier-New</Member>
+ <Member>New-Century-Schoolbook</Member>
+ <Member>Times-Roman</Member>
+ <Member>Trade-Gothic</Member>
+ <Member>Times-New-Roman</Member>
+ <Member>Times-NR-MT</Member>
+ <Member>Courier-New</Member>
+ <Member>Zapf-Dingbats</Member>
+ <Member>Gill-Sans</Member>
+ <Member>iso-serif</Member>
+ <Member>iso-sanserif</Member>
+ <Member>iso-monocase</Member>
+ <Member>LetterGothic12PitchBT</Member>
+ <Member>Monospace821</Member>
+ <Member>OCRB10PitchBT</Member>
+ <Member>OCR-A</Member>
+ <Member>OCR-B-10PitchBT</Member>
+ <Member>Computer-Modern-Typewriter</Member>
+ <Member>Computer-Modern-Sans</Member>
+ <Member>Computer-Modern</Member>
+ <Member>Computer-Modern-Caps-And-Small-Caps</Member>
+ </SimpleList>
+ </Answer>
+ </QandAEntry>
+ <QandAEntry>
+ <Question>
+ <Para>Why doesn't hyphenation work?</Para>
+ </Question>
+ <Answer>
+ <Para>Remember that your text must be fully justified
+ (<Literal>quadding: #t</Literal>), hyphenation must be on,
+ <Literal>hyphenation?: #t</Literal>, and a current language must
+ be selected (e.g., <Literal>language: 'EN</Literal>) for JadeTeX
+ to perform hyphenation.</Para>
+ </Answer>
+ </QandAEntry>
+ <QandAEntry>
+ <Question>
+ <Para>I'm using Norman Walsh's DocBook stylesheets and my
+ footnotes are coming up at the end of the document rather than
+ at the foot of each page. Why?</Para>
+ </Question>
+ <Answer>
+ <Para>The DocBook stylesheets need to be made aware that you are
+ using the TeX backend. Add <Option>-V tex-backend</Option> to
+ your <Command>openjade</Command> command-line.</Para>
+ </Answer>
+ </QandAEntry>
+ </QandASet>
+ </Section>
+</Article>
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:nil
+sgml-shorttag:nil
+sgml-namecase-general:nil
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:2
+sgml-indent-data:t
+sgml-parent-document:nil
+sgml-exposed-tags:nil
+sgml-local-catalogs:nil
+sgml-local-ecat-files:nil
+eval: (add-hook 'write-file-hooks 'time-stamp)
+time-stamp-start: "<!ENTITY last-update \""
+time-stamp-format: "%y-%02m-%02d %02H:%02M %Z"
+time-stamp-end: "\">"
+End:
+-->