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) 'man' and 'gnugroff':
 271    --------------------
 272
 273 For reading unformatted manual pages in UNIX 'roff' format like the
 274 ones coming with LyX you need 'manxxx.zip' and 'gnugroff.zip', both
 275 available from www.leo.org.
 276
 277 Hint:
 278 ----
 279 gnugroff.zip (README.OS2 date: Feb 24th 1994) from Leo has a little
 280 bug concerning doc macros:
 281
 282 Please change file prefix and suffix in groff/tmac/mdoc directory to
 283 the following:
 284
 285         doc-common
 286         doc-ditroff
 287         doc-nroff
 288         doc-syms
 289
 290 or adapt the content of
 291
 292         groff\tmac\doc
 293
 294 accordingly, so that it will find the distribution macros with
 295 non-standard names.
 296
 297 My proposed settings for man and groff are:
 298
 299 rem path to font directory
 300 SET GROFF_FONT_PATH=D:/USR/local/lib/GROFF/FONT
 301 rem path to tmac directory
 302 SET GROFF_TMAC_PATH=D:/USR/local/lib/GROFF/TMAC
 303 SET REFER=D:/XFREE86/USR/local/lib/GROFF/DICT/PAPERS/IND
 304 rem system primary codepage
 305 SET GROFF_TYPESETTER=cp850
 306 rem where man finds it manual pages
 307 SET MANPATH=D:/XFREE86/MAN;D:/XFREE86/usr/emx/doc/MAN
 308 rem necessary for correct formatting of BSD man pages
 309 set NROFF=GROFF -Tascii -mandoc
 310
 311
 312
 313 II. Installing a Binary Distribution:
 314     --------------------------------
 315
 316 0) Only for update: If you are upgrading from LyX v. 0.12.0,
 317    old documentation files in %HOME%/.lyx/doc/ and
 318    %X11ROOT%/XFree86/lib/X11/lyx/doc should be removed before
 319    unpacking (since they are read only). You might wish to make
 320    a backup, if you want to keep old docs.
 321
 322 1) Unpack the distribution in the directory %X11ROOT%
 323
 324 2) In config.sys SET LANG and LANGUAGE according to
 325    your preferences and restart.
 326      Beware: All programs supporting local
 327    languages will be affected, e.g.:
 328
 329 SET LANG=de_DE          rem german helpfiles will be used
 330 SET LANGUAGE=de_DE      rem german menus and messages
 331
 332 Note1: For keyboard problems read the XFree documentation. Lyx
 333         helpfiles also contain several hints.
 334
 335 Note2: German users should always use Layout; Document; Language:German
 336         and Encoding:latin1 to avoid problems with special characters.
 337         This might apply to other languages, too.
 338
 339 Note3: As distributed, LyX expects to find
 340         its internationalization files in the directory
 341  %X11ROOT%/XFree86/lib/X11/locale
 342         its system configuration files in the directory
 343  %X11ROOT%/XFree86/lib/X11/lyx
 344         If you unpacked the distribution in directory c:\foo, add
 345         the environment variables LYX_LOCALEDIR and LYX_DIR_11x
 346         to config.sys to point to c:/foo/XFree86/lib/X11/locale and
 347         c:/foo/XFree86/lib/X11/lyx as follows:
 348  SET LYX_LOCALEDIR=c:/foo/XFree86/lib/X11/locale
 349  SET LYX_DIR_11x=c:/foo/XFree86/lib/X11/lyx
 350         Note that, if you do not have any interest in having LyX display
 351         its messages in other languages than english, you can safely
 352         skip this step for LYX_LOCALEDIR.
 353
 354 3) At the root of the drive where your %HOME% resides, create a
 355    directory named tmp, if you haven't got one. LyX will need it, so
 356    remember not to delete it later.
 357
 358 4) If updating make a backup of %HOME%\.lyx\lyxrc.defaults as it will
 359    be changed.
 360    Read README and NEWS about updating and run
 361    Options;Reconfigure as indicated.
 362
 363 5) Configure LyX for your system by executing
 364      lyx
 365    and choose Options->Reconfigure in the menu bar.
 366    Watch the messages there.
 367
 368 6) If you don't have %HOME%\.lyx\lyxrc now then move
 369    %X11ROOT%\XFree86\lyxrc.example to %HOME%\.lyx\lyxrc.
 370    Verify if LYX is able to find the programs mentioned
 371    there and in %HOME%\.lyx\lyxrc.defaults. If not,
 372    change name and path as required. Read LyX doc in
 373
 374         Help->Customization
 375
 376   about customizing LyX for your needs. Read
 377
 378         Help->LatexConfiguration
 379
 380    to verify that all installed LaTeX packages which LyX can use
 381    have been detected.
 382    Remember to repeat the check after any 'Reconfigure'!
 383
 384 7) Printer setup is difficult. The most simple solution is to print to a
 385    postscript file and the use gvpm for printing. If you have installed
 386    'printlp.exe' of 'gnugroff.zip' from 'ww.leo.org', you could try to
 387    directly print to the local OS/2 spooler:
 388
 389 Excerpt from 'gnugroff.zip' README.OS2:
 390
 391 - New printlp and printdvi programs: Printlp captures all stdin input
 392   and spools it to "lpt1" (default) or the output device set in the
 393   environment variable LP_DEVICE. Printdvi captures all stdin input
 394   into a temporary file and calls the command "v" with the name as
 395   argument (v is the viewer in emTeX) or the command in the
 396   environment variable DVI_PRINT_COMMAND. If the command contains a
 397   %s, this will be replaced by the temporary file name.
 398
 399 I recommend to add to config.sys
 400
 401         SET DVI_PRINT_COMMAND=VP
 402
 403 and to add to your lyxrc
 404         \print_spool_command "printdvi"
 405
 406 or printlp for postscript printer or if you already configured a
 407 postscript filter according to the LyX documentation. A different solution
 408 to try is this one from Marcus von Cube (for xephem): Create an
 409
 410         /* xprint.cmd */
 411         parse arg file
 412         file = translate( file, "\", "/" )
 413         '@print /d:lpt2 /b' file
 414
 415 (you may want to change "print /d:lpt2 /b" to "printdvi") or create a
 416
 417         LPR-Installation:
 418
 419 If your %ETC%\INETD.LST contains the following line:
 420         printer tcp lpd
 421 and inetd is running, you should be able to use lpr:
 422         lpr -s localhost -p lpt2 -b <filename>
 423 It accepts "/" as path seperator.
 424
 425 This would mean adding
 426         \print_spool_command "lpr"
 427         \print_spool_printerprefix "-s localhost -p lpt2 -b"
 428
 429
 430 =======================================================================
 431
 432         B. Compiling/Installing the source distribution with emx:
 433            -----------------------------------------------------
 434
 435 ++++to be written++++++
 436
 437 Some hints:
 438
 439 Run configure.cmd from top level lyx-xxx directory of the source distribution.
 440 To create a smaller stripped version optimized for pentium on emx 0.9c type:
 441         configure.cmd --pentium-optimize
 442
 443 1,368,068 bytes (1.0.1 on emx 0.9c)
 444
 445 To create a smaller english-only version type:
 446         configure.cmd --disable-nls --pentium-optimize
 447 and then type
 448 cd src
 449 x11make
 450
 451 I recommend to run
 452         lib\configure.cmd --without-latex-config.
 453 The LaTeX configuration should better made when running LyX the first
 454 time and can always be repeated with Menu: Options->Reconfigure. So I
 455 added --without-latex-config to the call at the end of top configure.cmd.
 456
 457 Run the following if you have tee.exe:
 458         configure.cmd 2>&1|tee errors.log
 459 or
 460         configure.cmd --pentium-optimize 2>&1|tee errors.log
 461
 462 Read the logfile for any problems:
 463         cd.. & e errors.log
 464
 465 I recommend the following compilation settings:
 466
 467 set CC=gcc
 468 set CONFIG_SHELL=d:/bin/sh.exe
 469 set MAKE_SHELL=d:/bin/sh.exe
 470 set EMX_FIX_CMD="emxbind -a \$@ ..."
 471 SET C_INCLUDE_PATH=D:/XFREE86/INCLUDE/X11;d:/XFREE86/usr/emx/include
 472 set CPLUS_INCLUDE_PATH=D:/XFREE86/INCLUDE/X11;d:/XFREE86/usr/emx/include/cpp;d:/XFREE86/usr/emx/include
 473 set OBJC_INCLUDE_PATH=D:/XFREE86/INCLUDE/X11;d:/XFREE86/usr/emx/include
 474 SET LIBRARY_PATH=D:/XFREE86/LIB/X11;d:/XFREE86/usr/emx/lib
 475 set PROTODIR=d:/XFREE86/usr/emx/include/cpp/gen
 476 set GCCLOAD=5
 477 set GCCOPT=-pipe
 478 set emxopt=-c
 479 set MAKE=x11make.exe
 480 set shell=/bin/sh
 481
 482 Now you can run
 483
 484 x11make
 485
 486 directly from toplevel source directory.
 487
 488
 489 Note by Shigeru Miyata <miyata@kusm.kyoto-u.ac.jp>:
 490 ----------------------
 491 Run configure.cmd rather than configure!  Notice it is not the
 492 one in binary package, which is actually lib/configure.cmd, but
 493 the one in the top directory of the source distribution.
 494 It won't check the xpm version and other things BTW since I think
 495 I can assume rather uniform installations on OS/2 (actually the
 496 outdated error of the sh-script comes from an old header file,
 497 not from the library, though.  Remove the incompatible header or
 498 you will experience very weird, hard to track crashes).
 499 Makefiles are not perfect, however:
 500   - You have to type make in src/ directory;
 501   - If you do not specify --disable-nls, you have to make libintl
 502     first;
 503   - make install/bindist won't work, the makefile in po/ directory
 504     not generated;
 505   - In order to link xforms statically, "-lforms" in LYX_LIBS flag
 506     must be modified manually to "-lforms_s -lulib -lsocket";
 507   - And probably more ;-(
 508 Here is a statistic (exact size depends on libraries used,
 509 codepage, etc.):
 510                           unstripped      stripped
 511 emx09c                     10,735,882       1,634,308
 512 emx09d                     15,938,707       2,899,972
 513 emx09d (-fno-exceptions)   13,246,507       1,519,620
 514 In LyX 1.2, g++-2.8 (emx09d) or later will be the definite
 515 requirement.  (You cannot link 1.1 with emx09c, since the
 516 executable size far exceeds 70M unstripped due to template codes,
 517 for example.)
 518
 519
 520 \1a