INSTALL.OS2

   1
   2 INSTALL.OS2 file for OS/2 version of LyX 1.1.3
   3 by Shigeru Miyata <miyata@kusm.kyoto-u.ac.jp>
   4 modified by Arnd Hanses <Arnd.H.Hanses@rz.ruhr-uni-bochum.de>
   5 ##############################################################
   6
   7 - This INSTALL.OS2 file is a more detailed step by step guide on
   8   installing (or compiling) LyX and related useful (or even
   9   necessary) optional programs on OS/2.
  10
  11 - For general information on LyX please refer to the generic
  12   README and README.OS2. For generic compilation instructions
  13   refer to INSTALL. NEWS also contains important information.
  14
  15 Thanks to all contributors to this piece of documentation,
  16 namely Mika Kristian Laitio <lamikr@cc.jyu.fi>.
  17 I hope this will make live a bit easier for OS/2 LyXers.
  18
  19 Happy LyXing!
  20
  21
  22
  23         CONTENTS:
  24         ========
  25
  26 A. Installation Details
  27
  28    I.  Requirements/Optional Software
  29         1) XFree/2
  30         2) xpm.dll library (depends on distribution)
  31         3) 'GNU file utilities' and 'sed'
  32         4) LaTeX and 'dvips' (Options)
  33         5) 'Xdvi', 'gs', 'ghostview' or 'gv' (Options)
  34         6) 'perl' (Option)
  35         7) 'man' and 'gnugroff' (Options)
  36
  37    II. Installing a Binary Distribution
  38
  39
  40 B. Compiling/Installing the Source Distribution
  41
  42
  43
  44         A. Installation Details:
  45         ------------------------
  46
  47 * Introduction:
  48   ------------
  49   LyX and related programs have been ported from UNIX, following
  50   the UNIX design philosophy to do complex tasks combining small
  51   external standard utilities.
  52   UNIX is designed as a multi user system, where a professional
  53   system administrator maintains applications. On a single user
  54   workstation the user has to do this complicated job. Often
  55   programs assume you are familiar with the details of the UNIX
  56   standard. Even if documentation therefore seems complicated,
  57   you should try to read all the documents, UNIX manual (man)
  58   pages and FAQ a program supplies.
  59
  60
  61   I. Requirements/Optional Software:
  62      ------------------------------
  63
  64 1) XFree86 for OS/2
  65    ----------------
  66
  67    Use only a current version. Check
  68
  69         http://www-set.gmd.de/~veit/os2/xf86os2.html
  70
  71   An OS/2 specific FAQ answering most of the questions about
  72   using XFree86/2 is found always up to date at:
  73
  74         http://www-set.gmd.de/~veit/os2/xf86os2.html
  75
  76
  77 2) 'xpm.dll' library (if indicated in README.bin)
  78    -----------------
  79
  80    Check hobbes for 'xpm', or:
  81
  82         http://set.gmd.de/~veit/os2/xf86plib.html
  83
  84 3) 'sed' and 'GNU utilities' (Option)
  85    -------------------------
  86    - Required: 'sed.exe'
  87
  88    - Optional: 'groff.exe' for ASCII text export, 'GNU text
  89      utilities', 'man' to read man/man1/lyx.1.
  90
  91    You can search for OS/2 ports of those standard UNIX utilities on:
  92
  93         Hobbes or ftp.leo.org
  94
  95    in unix or gnu directories. Put the executables into a directory
  96    in PATH, e. g.:
  97
  98         d:\bin
  99    (Hint: Often ports assume a UNIX-like 'sh.exe' in '\bin'!)
 100
 101     and put the dll's into a directory in LIBPATH.
 102
 103
 104 4) 'LaTeX' and 'dvips' (Option)
 105    -------------------
 106
 107    You will need them for printable output. With emTeX make sure that
 108    you have latex2e.cmd in \emtex\bin-directory. If it is missing (i.
 109    e. if you installed emtex from emtex-bin-os2.zip) create it using
 110    the following commands from \emtex\doc\english:
 111
 112         cd \emtex\btexfmts
 113         makefmt 386 latex2e US 8bit -b \emtex\bin\latex2e
 114
 115    Now you can print US-english text. If LyX cannot find the files
 116    'latex.cmd' or 'latex2e.cmd' (available if your LaTeX is installed
 117    correctly) it will work with standard options. Then you can use it
 118    as an editor to write files in native (*.lyx) and LaTeX (*.tex)
 119    format. You can later print LaTeX files on every system with a
 120    proper LaTeX2e installation (or send them to your editor).
 121
 122  * A preconfigured version of emTeX may be found searching:
 123
 124         http://tsikora.tiac.net/os2/os2-body.html
 125
 126    for 'emTeX'. Install first 'emTeX' and then unzip 'dvips583' into
 127    your emtex root directory.
 128
 129  * Additional TeX macros for special purposes (e. g. Babel) are
 130    available on your local CTAN mirror. There you will find also the
 131    documentation how to install it. Please read Help->LaTeXconfig for
 132    availability of the LaTeX packages after installing LyX.
 133
 134    Babel is - unlike with almost all other recent TeX distributions -
 135    not standard with emTeX. For non-US languages you can install Babel
 136    and recreate the LaTeX format files with the correct languages
 137    after selected, reading the respective original documentation. All
 138    further problems should be discussed with the author (Eberhard
 139    Mattes) and on emTeX list.
 140
 141  * In Germany I recommend:
 142
 143 ftp://ftp.dante.de/tex-archive/help/Catalogue/catalogue.html
 144
 145    as the starting point for browsing CTAN. Dvips is also available
 146    on:
 147
 148 http://www.leo.org/pub/comp/os/os2/leo/emTeX/contrib/index.html.
 149
 150
 151
 152
 153 5) 'Xdvi', 'gs', 'ghostview' or 'gv' with 'xaw3d' (Options)
 154    ----------------------------------------------
 155
 156  * For fast preview you need XDVI.
 157
 158 [Excerpt from Peter Ganten's README.OS2 (missing in the package):
 159  ....
 160  -- Xdvi now understands drive letters and semicolons as path
 161     separators
 162  -- Xdvi is now compiled with the SEARCH-SUBDIRECTORIES flag
 163  -- Xdvi will now call ghostscript to display postscript-pictures (see
 164     note below)
 165  -- MakeTeXPk.cmd will now look into your psfonts.map file and call
 166     gsftopk to display postscript fonts
 167  -- Xdvi will now use virtual fonts ... ]
 168
 169  * For perfect preview of the printed
 170    output of LyX you need ghostview or gv (the latter needs xaw3d.dll
 171    being renamed to xaw.dll) and a special version of Ghostscript for
 172    X11. (The standard 'gsos2' lacks '-sDEVICE=x11' and will *not*
 173    work!).
 174
 175  * OS/2 ports (and necessary info) can be found using the links in:
 176
 177 http://www-set.gmd.de/~veit/os2/xf86ported.html,
 178
 179    and Ghostscript in Michael Holzapfel's page:
 180
 181 http://www.ime.rwth-aachen.de/~michael/os2/ghostscript/index.html.
 182
 183  * Configuration of EmTeX and XDVI to work poperly is a bit tricky,
 184    as they use different directory structures and syntax:
 185
 186     - You can export documents in tex format and preview later with
 187       emTeX's tools.
 188
 189     - Else you must unzip 'xdvi.zip' and 'xaw3d.zip' in %x11root%. Then
 190       correct the line
 191
 192         mapfile='d:\emtex\data\dvips\psfonts.map'
 193
 194       in 'MakeTeXpk.cmd' so that it points to the psfonts.map file
 195       which came with dvips*.zip'. You will find this 'MakeTeXpk.cmd'
 196       in
 197
 198         %x11root%\xfree86\bin
 199
 200       SET XDVIFONTS to your upper TeX fonts directory 'foo':
 201
 202         SET XDVIFONTS=x:/foo/*/%ddpi/%f.%p
 203
 204       The asterisk means: search subdirectories and will be expanded,
 205       e.g. to
 206
 207 x:/foo/pixel.lj/300dpi/fontname.pk
 208
 209       For preview of Postscript fonts (Type 1) you need the
 210       corresponding virtual fonts und must use SET XDVIVFS like above:
 211
 212 SET XDVIVFS=D:/foo/vf;D:/foo/vf/adobe
 213
 214      There is no possibility to search subdirectories here, so you have
 215      to list all directories with virtual fonts.
 216
 217   * Gv needs to find gs.exe: You should rename gsos2.exe to gs.exe,
 218     and move the executables and the dll to %PATH%. [According to the
 219     original documentation moving the dll to %LIBPATH% should work as
 220     well. But on my system it doesn't.] Also you should add to
 221     config.sys:
 222
 223 SET GS_LIB=x:/path_to_your_gs2dll.dll;*.ps_helper_files;type_1fonts
 224 SET GS_FONTPATH=path_to_aditional_fonts_not_included_in_fontmap
 225
 226     For details please refer to the (often complicated) docs of the
 227     respective packages.
 228
 229
 230 Here an example:
 231 ...
 232 SET GS_LIB=D:/HYOTY/GSTOOLS/gs5.50;E:/PSFONTS;
 233 SET GS_FONTPATH=D:/APPS/GSTOOLS/gs5.50/FONTS;E:/PSFONTS;
 234
 235 rem This is where EmTeX tree begins
 236 SET EMTEXDIR=D:\EMTEX
 237
 238 rem  This is where Xdvi/dvips look for fonts (bitmap, virtual, type1
 239 fonts, resp.)
 240 SET XDVIFONTS=D:/texfonts/*/%ddpi/%f.%p
 241 SET XDVIVFS=D:/texfonts/vf/%f.vf
 242 SET T1FONTS=D:\PSFONTS;D:\XFREE86\LIB\X11\FONTS\TYPE1;
 243 SET TEXCONFIG=D:/EMTEX/data/dvips
 244
 245 rem  TeX/LaTeX has to find its font metrics (*.tfm)
 246 SET TEXTFM=D:\EMTEX\tfm!!
 247
 248 rem  TeX/LaTeX has to find its macros, etc. (*.sty; *.cls; *.tcp; etc.)
 249 SET TEXINPUT=D:\EMTEX\TEXINPUT\LATEX2E!!;D:\EMTEX\TEXINPUT!!
 250
 251 rem  This is where dvipm/Xdvi looks for input data to preview
 252 SET DVIDRVinput=D:\EMTEX\doc;D:\EMTEX\doc\latex;D:\EMTEX\doc\english;
 253 SET DVIDRVGRAPH=D:\EMTEX\DOC
 254 SET XDVIFIGS=D:/EMTEX/data/dvips;D:/HYOTY/GSTOOLS/gs5.50;E:/PSFONTS;
 255 SET indexstyle=D:\emtex\idxstyle
 256
 257 rem Call mf386.exe to render missing bitmap fonts
 258 SET MFJOBOPT=/3
 259
 260 SET indexstyle=D:\XFREE86\USR\emtex\idxstyle
 261 SET EMTEXED=emacsclient +%1 %2
 262
 263 rem Where chktex stores its user configuration
 264 SET chktexrc=%home%
 265 .......
 266
 267 Do not copy it! You need to adapt it to your directory structure.
 268
 269
 270 6) perl:
 271    ----
 272
 273 For LaTeX import (relyx.cmd) you need perl:
 274 Check your local CPAN server for a recent OS/2 port or try:
 275
 276         http://www.perl.org
 277
 278 Note:
 279 ----
 280 If perl cannot find its modules and libraries it has a hardcoded
 281 path chosen at compile time that does not match your configuration.
 282 You can recompile with your directory structure or exchange the path
 283 as follows (from man perlos2):
 284
 285        PERLLIB_PREFIX
 286
 287        Specific for EMX port. Should have the form
 288
 289          path1;path2
 290
 291        or
 292
 293          path1 path2
 294
 295        If the beginning of some prebuilt path matches path1, it
 296        is substituted with path2.
 297
 298        Should be used if the perl library is moved from the
 299        default location in preference to PERL(5)LIB, since this
 300        would not leave wrong entries in @INC.  Say, if the
 301        compiled version of perl looks for @INC in f:/perllib/lib,
 302        and you want to install the library in h:/opt/gnu, do
 303
 304          set PERLLIB_PREFIX=f:/perllib/lib;h:/opt/gnu"
 305 On my system 'f:/perllib/lib' is hardcoded and has to be exchanged
 306 for 'd:/bin/perllib/lib'. Also like many other programs ported from
 307 UNIX (unfortunately this is also true for many XFree/2 programs) it
 308 uses a UNIX-like sh; you should give its path.
 309 I recommend sh.exe of pdksh.zip; other shells have problems.
 310
 311 Here an example of my config.sys:
 312
 313 rem Not default directory of perllib/lib (here:d:\bin)
 314 set PERLLIB_PREFIX=f:/perllib/lib;d:/bin/perllib/lib
 315 rem Where sh.exe of pdksh.zip resides:
 316 set PERL_SH_DIR=D:\bin
 317
 318 excerpt from perlos2:
 319
 320       After you installed the components you needed and updated
 321        the Config.sys correspondingly, you need to hand-edit
 322        Config.pm. This file resides somewhere deep in the
 323        location you installed your perl library, find it out by
 324
 325          perl -MConfig -le "print $INC{'Config.pm'}"
 326
 327        You need to correct all the entries which look like file
 328        paths (they currently start with f:/).
 329
 330        Warning
 331
 332        The automatic and manual perl installation leave
 333        precompiled paths inside perl executables. While these
 334        paths are overwriteable (see the section on
 335        PERLLIB_PREFIX, the section on PERL_SH_DIR), one may get
 336        better results by binary editing of paths inside the
 337        executables/DLLs.
 338
 339 7) 'man' and 'gnugroff':
 340    --------------------
 341
 342 For reading unformatted manual pages in UNIX 'roff' format like the
 343 ones coming with LyX you need 'manxxx.zip' and 'gnugroff.zip', both
 344 available from www.leo.org.
 345
 346 Hint:
 347 ----
 348 gnugroff.zip (README.OS2 date: Feb 24th 1994) from Leo has a little
 349 bug concerning doc macros:
 350
 351 Please change file prefix and suffix in groff/tmac/mdoc directory to
 352 the following:
 353
 354         doc-common
 355         doc-ditroff
 356         doc-nroff
 357         doc-syms
 358
 359 or adapt the content of
 360
 361         groff\tmac\doc
 362
 363 accordingly, so that it will find the distribution macros with
 364 non-standard names.
 365
 366 My proposed settings for man and groff are:
 367
 368 rem path to font directory
 369 SET GROFF_FONT_PATH=D:/USR/local/lib/GROFF/FONT
 370 rem path to tmac directory
 371 SET GROFF_TMAC_PATH=D:/USR/local/lib/GROFF/TMAC
 372 SET REFER=D:/XFREE86/USR/local/lib/GROFF/DICT/PAPERS/IND
 373 rem system primary codepage
 374 SET GROFF_TYPESETTER=cp850
 375 rem where man finds it manual pages
 376 SET MANPATH=D:/XFREE86/MAN;D:/XFREE86/usr/emx/doc/MAN
 377 rem necessary for correct formatting of BSD man pages
 378 set NROFF=GROFF -Tascii -mandoc
 379
 380
 381
 382 II. Installing a Binary Distribution:
 383     --------------------------------
 384
 385 0) Only for update: If you are upgrading from LyX v. 0.12.0,
 386    old documentation files in %HOME%/.lyx/doc/ and
 387    %X11ROOT%/XFree86/lib/X11/lyx/doc should be removed before
 388    unpacking (since they are read only). You might wish to make
 389    a backup, if you want to keep old docs.
 390
 391 1) Unpack the distribution in the directory %X11ROOT%
 392
 393 2) In config.sys SET LANG and LANGUAGE according to
 394    your preferences and restart.
 395      Beware: All programs supporting local
 396    languages will be affected, e.g.:
 397
 398 SET LANG=de_DE          rem german helpfiles will be used
 399 SET LANGUAGE=de_DE      rem german menus and messages
 400
 401 Note1: For keyboard problems read the XFree documentation. Lyx
 402         helpfiles also contain several hints.
 403
 404 Note2: German users should always use Layout; Document; Language:German
 405         and Encoding:latin1 to avoid problems with special characters.
 406         This might apply to other languages, too.
 407
 408 Note3: As distributed, LyX expects to find
 409         its internationalization files in the directory
 410  %X11ROOT%/XFree86/lib/X11/locale
 411         its system configuration files in the directory
 412  %X11ROOT%/XFree86/lib/X11/lyx
 413         If you unpacked the distribution in directory c:\foo, add
 414         the environment variables LYX_LOCALEDIR and LYX_DIR_11x
 415         to config.sys to point to c:/foo/XFree86/lib/X11/locale and
 416         c:/foo/XFree86/lib/X11/lyx as follows:
 417  SET LYX_LOCALEDIR=c:/foo/XFree86/lib/X11/locale
 418  SET LYX_DIR_11x=c:/foo/XFree86/lib/X11/lyx
 419         Note that, if you do not have any interest in having LyX display
 420         its messages in other languages than english, you can safely
 421         skip this step for LYX_LOCALEDIR.
 422
 423 3) At the root of the drive where your %HOME% resides, create a
 424    directory named tmp, if you haven't got one. LyX will need it, so
 425    remember not to delete it later.
 426
 427 4) If updating make a backup of %HOME%\.lyx\lyxrc.defaults as it will
 428    be changed.
 429    Read README and NEWS about updating and run
 430    Options;Reconfigure as indicated.
 431
 432 5) Configure LyX for your system by executing
 433      lyx
 434    and choose Options->Reconfigure in the menu bar.
 435    Watch the messages there.
 436
 437 6) If you don't have %HOME%\.lyx\lyxrc now then move
 438    %X11ROOT%\XFree86\lyxrc.example to %HOME%\.lyx\lyxrc.
 439    Verify if LYX is able to find the programs mentioned
 440    there and in %HOME%\.lyx\lyxrc.defaults. If not,
 441    change name and path as required. Read LyX doc in
 442
 443         Help->Customization
 444
 445   about customizing LyX for your needs. Read
 446
 447         Help->LatexConfiguration
 448
 449    to verify that all installed LaTeX packages which LyX can use
 450    have been detected.
 451    Remember to repeat the check after any 'Reconfigure'!
 452
 453 7) Printer setup is difficult. The most simple solution is to print to a
 454    postscript file and the use gvpm for printing. If you have installed
 455    'printlp.exe' of 'gnugroff.zip' from 'ww.leo.org', you could try to
 456    directly print to the local OS/2 spooler:
 457
 458 Excerpt from 'gnugroff.zip' README.OS2:
 459
 460 - New printlp and printdvi programs: Printlp captures all stdin input
 461   and spools it to "lpt1" (default) or the output device set in the
 462   environment variable LP_DEVICE. Printdvi captures all stdin input
 463   into a temporary file and calls the command "v" with the name as
 464   argument (v is the viewer in emTeX) or the command in the
 465   environment variable DVI_PRINT_COMMAND. If the command contains a
 466   %s, this will be replaced by the temporary file name.
 467
 468 I recommend to add to config.sys
 469
 470         SET DVI_PRINT_COMMAND=VP
 471
 472 and to add to your lyxrc
 473         \print_spool_command "printdvi"
 474
 475 or printlp for postscript printer or if you already configured a
 476 postscript filter according to the LyX documentation. A different solution
 477 to try is this one from Marcus von Cube (for xephem): Create an
 478
 479         /* xprint.cmd */
 480         parse arg file
 481         file = translate( file, "\", "/" )
 482         '@print /d:lpt2 /b' file
 483
 484 (you may want to change "print /d:lpt2 /b" to "printdvi") or create a
 485
 486         LPR-Installation:
 487
 488 If your %ETC%\INETD.LST contains the following line:
 489         printer tcp lpd
 490 and inetd is running, you should be able to use lpr:
 491         lpr -s localhost -p lpt2 -b <filename>
 492 It accepts "/" as path seperator.
 493
 494 This would mean adding
 495         \print_spool_command "lpr"
 496         \print_spool_printerprefix "-s localhost -p lpt2 -b"
 497
 498
 499 =======================================================================
 500
 501         B. Compiling/Installing the source distribution with emx:
 502            -----------------------------------------------------
 503
 504 ++++to be written++++++
 505
 506 Some hints:
 507
 508 Run configure.cmd from top level lyx-xxx directory of the source distribution.
 509 To create a smaller stripped version optimized for pentium on emx 0.9c type:
 510         configure.cmd --pentium-optimize
 511
 512 1,368,068 bytes (1.0.1 on emx 0.9c)
 513
 514 To create a smaller english-only version type:
 515         configure.cmd --disable-nls --pentium-optimize
 516 and then type
 517 cd src
 518 x11make
 519
 520 I recommend to run
 521         lib\configure.cmd --without-latex-config.
 522 The LaTeX configuration should better made when running LyX the first
 523 time and can always be repeated with Menu: Options->Reconfigure. So I
 524 added --without-latex-config to the call at the end of top configure.cmd.
 525
 526 Run the following if you have tee.exe:
 527         configure.cmd 2>&1|tee errors.log
 528 or
 529         configure.cmd --pentium-optimize 2>&1|tee errors.log
 530
 531 Read the logfile for any problems:
 532         cd.. & e errors.log
 533
 534 I recommend the following compilation settings:
 535
 536 set CC=gcc
 537 set CONFIG_SHELL=d:/bin/sh.exe
 538 set MAKE_SHELL=d:/bin/sh.exe
 539 set EMX_FIX_CMD="emxbind -a \$@ ..."
 540 SET C_INCLUDE_PATH=D:/XFREE86/INCLUDE/X11;d:/XFREE86/usr/emx/include
 541 set CPLUS_INCLUDE_PATH=D:/XFREE86/INCLUDE/X11;d:/XFREE86/usr/emx/include/cpp;d:/XFREE86/usr/emx/include
 542 set OBJC_INCLUDE_PATH=D:/XFREE86/INCLUDE/X11;d:/XFREE86/usr/emx/include
 543 SET LIBRARY_PATH=D:/XFREE86/LIB/X11;d:/XFREE86/usr/emx/lib
 544 set PROTODIR=d:/XFREE86/usr/emx/include/cpp/gen
 545 set GCCLOAD=5
 546 set GCCOPT=-pipe
 547 set emxopt=-c
 548 set MAKE=x11make.exe
 549 set shell=/bin/sh
 550
 551 Now you can run
 552
 553 x11make
 554
 555 directly from toplevel source directory.
 556
 557
 558 Note by Shigeru Miyata <miyata@kusm.kyoto-u.ac.jp>:
 559 ----------------------
 560 Run configure.cmd rather than configure!  Notice it is not the
 561 one in binary package, which is actually lib/configure.cmd, but
 562 the one in the top directory of the source distribution.
 563 It won't check the xpm version and other things BTW since I think
 564 I can assume rather uniform installations on OS/2 (actually the
 565 outdated error of the sh-script comes from an old header file,
 566 not from the library, though.  Remove the incompatible header or
 567 you will experience very weird, hard to track crashes).
 568 Makefiles are not perfect, however:
 569   - You have to type make in src/ directory;
 570   - If you do not specify --disable-nls, you have to make libintl
 571     first;
 572   - make install/bindist won't work, the makefile in po/ directory
 573     not generated;
 574   - In order to link xforms statically, "-lforms" in LYX_LIBS flag
 575     must be modified manually to "-lforms_s -lulib -lsocket";
 576   - And probably more ;-(
 577 Here is a statistic (exact size depends on libraries used,
 578 codepage, etc.):
 579                           unstripped      stripped
 580 emx09c                     10,735,882       1,634,308
 581 emx09d                     15,938,707       2,899,972
 582 emx09d (-fno-exceptions)   13,246,507       1,519,620
 583 In LyX 1.2, g++-2.8 (emx09d) or later will be the definite
 584 requirement.  (You cannot link 1.1 with emx09c, since the
 585 executable size far exceeds 70M unstripped due to template codes,
 586 for example.)
 587
 588
 589 \1a