About this manual
Introduction
These pages, and those for the QUASI site are maintained as
a set of precursor files, which are processed by a hypertext
pre-processor (htp)
into html pages. The precursor pages are held in the SVN
repository.
This structure has been adopted because it allows elements of web site
design (style, icons, navigation tools etc) are kept in separate files
to the page content. This helps content production proceed in the
absence of any idea what the final design may be. A new style,
including new fonts/colours and maybe other technologies like
JavaScript or frames can be applied to the whole site without editing
every page. Currently the navigation panel is placed on the left
using a two-column table.
Generating the HTML
Once you have obtained a local copy, you should first build htp. The
C source code is included in the repository, typing make (after you have
configured ChemShell) in the
htp subdirectory should do the trick. You will need a C compiler, if
it is not what was used as $CC in the configure process, edit the Makefile accordingly.
The files in a given directory can then be generated by typing make
in the relevant directory.
Making changes to the pages
Obviously, the pre-processing step requires that the precursor files
are edited rather than the resulting HTML. These are names with
suffixes .htp for the main text sections and .nav for the navigational
menus. At present the .nav files should be referenced from head.htp
so that they appear on the left hand column of the main table. They
should be conditionally included using <if> and <\if> so
that they only appear when the corresponding text page is showing
on the right hand side of the screen, the existing files should
indicate how this is done.
You should make sure that each new .htp file has the correct
macro invocations at the start and finish (see opt.htp as an example)
don't include tags like <html> <body> <head> etc.
since these are added at pre-process time.
Maths processing
This is one of the more problematic aspects of maintaining an HTML
format manual, as I am not aware of a satisfactory way of including
in-line and display equations, except as small image files. If you
have latex2html installed locally, the pre-processing step is
capable of using it to typeset equations that are included as
embedded latex, as follows. The equation macro is defined
in head.htp, which is included into all pages at pre-process time.
<p>
<use equation image=example.gif latex="$$V = \frac{k}{2}(r-r_0)^2$$">
This looks like this after processing
Not perfect, the result could be improved by associating some size parameters with
the included gif. Note that because most sites do not have latex2html working
the latex -> gif processing is suppressed, you can activate it by editing
head.htp.
Conventions
The following list summarises the conventions I am trying to adopt for the
manual. For various reasons the manual doesn't comply with them yet.
- Always provide an argument table for the command (in due course they should
all be converted to the 5-column style, see hdlcopt.html). For neatness, set the
columns widths for the first row using the (htp)
macros <cw1> etc..
- use <tt> tags around strings that are to be used in scripts
- use <b> tags around ChemShell command names - maybe also <tt>
would be better?
- be careful with <PRE> tags. They tend to make a page too broad for
print. A 65 columns is the maximum width using a size
of 9pt in test.css.
- Argument types to be used: keyword (for stings that are defined
in ChemShell, choices should be given), string, integer, real,
<use fragment_link> Fragment tag
,
<use zmatrix_link> Zmatrix tag
,
<use matrix_link> Matrix tag
,
<use field_link> Field tag
,
<use bool_link> Boolean
,
<use variable_link> Tcl variable
,
<use list_link> Tcl List
,
<use listopt_link> Output keyword
,
<use gegi_link> Energy/Gradient code
.
|
