diff options
Diffstat (limited to 'Master/texmf-dist/doc/jadetex/base/install.sgm')
-rw-r--r-- | Master/texmf-dist/doc/jadetex/base/install.sgm | 474 |
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…</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: +--> |