Prev Next

Unix Installation and Testing

Requirements
     source-highlight
     Octave
     flex, bison
Download OMhelp
Distribution Directory
CMake Command
     source_highlight_prefix
     have_flex_and_bison
     omhelp_prefix
     omhelp_datadir
     omhelp_c_flags
     omhelp_build_type
Build Executable
OMhelp Documentation
     Getting Started
     Developer Documentation
     User Documentation
Install OMhelp
Getting Started
Spelling List
     english.wrd
     local.wrd
     dictionary.bin
Vim Editor

Requirements
Building OMhelp requires that a C, C++ compiler, git , and cmake version 2.8 or greater are in your execution path. These are some other optional requirements listed below:

source-highlight
Using the srcfile command is optional. If you are using this command, you will need the source-highlight library which in turn requires the boost_regex library.

Octave
The current version of source-highlight does not support Octave source code ( *.m ). Adding Octave to the list supported by source-highlight is optional. The script highlight.sh can be used for this purpose.

flex, bison
Changing the src/omhelp.y, latex.y, or latex.l file is optional. If you are doing this, you will need flex and bison in your execution path.

Download OMhelp
Use the following commands to get the current version of OMhelp
     git clone https://github.com/bradbell/omhelp.git omhelp.git
     cd omhelp.git
 Use the following commands to determine the corresponding git_hash and version:
     git show-ref | grep 'refs/heads/master'
     grep '^SET(omhelp_version' CMakeLists.txt
 Use the following commands to checkout as specific git_hash and check the corresponding version
     git checkout git_hash
     grep '^SET(omhelp_version' CMakeLists.txt
 .

Distribution Directory
For this download procedure, we refer to omhelp.git as the distribution_directory .

CMake Command
Execute the following commands:
     cd distribution_directory
     mkdir build
     cd build
     cmake \
          -D source_highlight_prefix=source_highlight_prefix  \
          -D have_flex_and_bison=have_flex_and_bison \
          -D omhelp_prefix=omhelp_prefix  \
          -D omhelp_datadir=omhelp_datadir  \
          -D omhelp_c_flags=omhelp_c_flags  \
          -D omhelp_build_type=omhelp_build_type \
          ..
 Only the program name cmake, and the distribution directory reference .., are required. The other entries use default values if they are not specified.

source_highlight_prefix
The default value for source_highlight_prefix is /usr. This prefix installs the source-highlight library in one of the following:
     /usr/lib/libsource-highlight.*
     /usr/lib64/libsource-highlight.*
have_flex_and_bison
If you have these flex, bison , you should specify this value as YES. Otherwise, you should use NO (the default).

omhelp_prefix
The default value for omhelp_prefix is /usr; i.e., by default the OMhelp executable is installed in 
 
     /usr/bin/omhelp
If you do not have write permission for /usr, you must specify a prefix . If omhelp_prefix/bin is not in your path, you will have to specify the entire path omhelp_prefix/bin/omhelp when you execute it.

omhelp_datadir
The data files used by OMhelp are installed in
     omhelp_prefix/omhelp_datadir/omhelp_data
 The default value for omhelp_datadir is share.

omhelp_c_flags
These are extra flags, besides the debug and release flags, that are used during compilation. The default value for omhelp_c_flags is none.

omhelp_build_type
This should be either debug (compile for debugging) or release (compile for speed). The default, if it is not specified, is debug.

Build Executable
In the distribution_directory/build execute the following command 
 
     make
This should build the program
     distribution_directory/build/src/omhelp
 If you are using Cygwin or MinGw, the file omhelp may possibly be omhelp.exe. If you have fortran, and CMake can figure out how to link C to Fortran, the following program will also be built
     distribution_directory/build/omh/getstarted/run_all
OMhelp Documentation
It is no longer necessary to build the OMhelp documentation before installing OMhelp; i.e., you can skip these steps.

Getting Started
The following commands will run OMhelp on a simple example for the get_started section. The output printed by OMhelp is stored in the file omhelp.xam.log, which is used when building the user and developer documentation. 
 
     mkdir xam
     cd xam
     cp ../omh/getstarted/simple_example.omh .
     mkdir htm
     cd htm
     ../../build/src/omhelp ../simple_example.omh > ../../omhelp.xam.log \
          -noframe -debug -omhelp_dir ../../omhelp_data
     cd ../..
Note that the xam and xam/htm directories may already exist and the mkdir commands may not be necessary.

Developer Documentation
Starting in the distribution_directory directory, the following commands create the developer documentation in the distribution_directory/dev : 
 
     mkdir dev
     cd dev
     ../build/src/omhelp ../src/omh/omhelp.omh > ../omhelp.dev.log \
          -noframe -debug -omhelp_dir ../omhelp_data
     cd ..
This should complete without error, and so also functions as a test of the distribution.

User Documentation
Starting in the distribution_directory directory, the following commands create the user documentation in the distribution_directory/doc : 
 
     mkdir doc
     cd doc
     ../build/src/omhelp ../omh/overview.omh > ../omhelp.doc.log \
          -noframe -debug -omhelp_dir ../omhelp_data
     cd ..
This should complete without error, and so also functions as a test of the distribution.

Install OMhelp
In the distribution_directory/build execute the following command 
 
     make install

Getting Started
See get_started

Spelling List
The OMhelp utility files are stored in the distribution_directory/omhelp_data directory. The spelling lists below are a subset of these files.

english.wrd
The file distribution_directory/omhelp_data/english.wrd is a list of standard english words. The words must be in alphabetic order, lower case, and contain only letters. For example, 
 
     a
     aardvark
     aardvarks
     ...
A default english.wrd file is distributed with OMhelp.

local.wrd
The file distribution_directory/omhelp_data/local.wrd is an optional list of special words, not in english.wrd that are to be considered correctly spelled. These words must also be in alphabetic order, lower case, and contain only letters.

dictionary.bin
OMhelp combines the files english.wrd and local.wrd to form
     distribution_directory/omhelp_data/dictionary.bin
 If you make any changes to english.wrd or local.wrd, the file dictionary.bin should be deleted. A new dictionary.bin that combines the words english.wrd and local.wrd can be created and installed by executing following commands in the distribution_directory directory: 
 
     rm omhelp_data/dictionary.bin
     cd build/omh/getstarted
     ../../src/omhelp \
          ../../../omh/getstarted/simple_example.omh \
          -omhelp_dir ../../../omhelp_data
     cd ../..
     make install

Vim Editor
The following vim editor syntax highlighting files are installed in:
     omhelp_prefix/omhelp_datadir/omhelp_data/vim/syntax/omhelp.vim
     omhelp_prefix/omhelp_datadir/omhelp_data/vim/ftdetect/omhelp.vim
 If you copy the respective files to
     $HOME/.vim/syntax/omhelp.vim
     $HOME/.vim/ftdetect/omhelp.vim
 you will be able to use OMhelp syntax highlighting. The vim commands 
 
     :syntax on
     :set syntax=omhelp
will turn on OMhelp syntax highlighting for the file you are currently editing. You could convert back to the original highlighting by executing the command 
 
     :echo &filetype
     :set syntax=%filetype%
where filetype is the value echoed by the :echo &filetype command. You may also want to automatically turn on vim syntax highlighting. You can do this by placing the following text in the file .vimrc in your home directory: 
 
     :syntax on
Input File: omh/installunix.omh