CStyleX XSLT Genereated Documentation for C Libraries http://www.ioplex.com/~miallen/cstylex/ Sat May 8 17:49:21 EDT 2004 cstylex-0.2.0 released All stylesheets have been updated. In the future, libmba tends to have the current xsl files. Wed Jul 23 04:18:32 EDT 2003 cstylex-0.1.2 released Prototypes containing parameters like 'char *row[]' would confuse man.xsl. Brackets are now supported properly in man pages. The man.xsl stypesheet has also been adjusted to properly display '\0'. Previously troff would interpret the '\' as an escape. These are now escaped with '\\' which troff displays correctly. The ref.xsl stylesheet has been adjusted to only print the Synopsis and Description sections if a pre child is present. Sun Mar 23 03:56:08 EST 2003 cstylex-0.1.1 released Multiple tags will result in #include statements for each in the synopsis. Tip: tabs rather than spaces are required in 
 sections to
indent  code  in a man page (such as the members of a structure). Also, the
inlined  CSS  generated by ref.xsl hsa been adjusted; it now specifies font
size  as  'x-small'  rather than '10pt' so that it may be changed using the
regular browser controls (e.g. Ctrl-/Ctrl+ with Mozilla). 

--

The CStyleX package provides ref.xsl, man.xsl, and proj.xsl XSLT transforms
that will convert an XML input file describing a library of C routines into
an HTML Reference, man pages, and project webpage. Examples include: 

  http://www.ioplex.com/~miallen/libmba/
  http://www.ioplex.com/~miallen/domc/
  http://www.ioplex.com/~miallen/encdec/

CStyleX  does  not  attempt  to  parse C source or headers. The author must
create   an  XML  input  file  that  conforms  to  a  certain  syntax  (see
xml/SYNTAX.txt)  and  run  'make'  to  output  the  documentation.  An XSLT
processor   is   required.   The   Makefile   is   configured   to  use  XT
(http://www.blnz.com/xt/). The exact instructions are as follows: 

I N S T A L L A T I O N

o  Unpack  cstylex-y.z.tar.gz  in  your  project directory and rename it to
'docs' (or something appropriate). This directory contains the following: 

  Makefile   - Makefile  to build the HTML reference, man pages, or project
               web page
  man        - Directory in which generated man pages will be written
  README.txt - This file
  ref        - Directory in which generated HTML reference will be written
  www        - Directory in which the project web page will be generated
  xml        - Input   source  XML,  "blank.xml"  to  start  new  interface
               descriptions,   and  man.xsl,  ref.xsl,  and  proj.xsl  XSLT
               transforms 
  xml/README.txt - Hierarchy  of  tags  to  aid  in  creating a valid input
               files.  See  other  input  files  from example projects like
               libmba, domc, and encdec.

o  Edit  XSLCMD  in  the  Makfile  to  reference  your  XSLT processor. The
processor  referenced  by default is XT where appears to be available here:
http://www.blnz.com/xt/index.html. If you choose to use a different one, it
may  be  necessary  to  change  the way in which parameters are passed. Run
'make'  and adjust as necessary to build the default 'mylib' with interface
'foo'.

o  Globally search and replace mylib with the name of your library. It will
be necessary to edit the Makefile and rename xml/mylib.xml.

o For each module in your library use (copy) xml/foo.xml as a blank. Follow
examples  from libmba, encdec, and domc and refer to xml/README.txt for tag
hierarchy.  Run  make frequently. If you get "character not allowed" errors
with XT check your entity references and end quotes. Characters like '>' or
'&'  need  to  be  escaped  in  XML  with entity references like '>' and
'&'.

o  To  build  the  toc  for  the  reference change the entity references in
xml/mylib.xml  (or  whatever  you  renamed it to) to include your interface
definitions. If you have only one interface in the reference you can simply
choose  to  ignore  the framed index.html. If you have many interfaces from
different  packages  they  can  be  included in ref.xml to make one big API
reference.