\title{{\sl Introduction to ACSDOC}\\ \bigskip \bigskip } \author{\bf Piet Hut and Jun Makino} \maketitle \thispagestyle{empty} :tableofcontents: = Preface This is a short introduction to ACSDOC, a document-processing system which can generate latex or html files from a common, easy-to-write text. = Simple Example :command: cd examples; ruby ../acsdoc.rb simpleexample.ok :command: cd examples; ruby ../acsdoc.rb --tolatex simpleexample.ok :command: cd examples; latex simpleexample :command: cd examples; dvips -E -l 1 -x 1900 -o simpleexample.ps simpleexample :command: cd examples; convert simpleexample.ps simpleexample.jpeg The following is a simple example. :include: examples/simpleexample.ok This one creates the output shown in figure ref(fig1) :figure: examples/simpleexample.jpeg 8cm fig1 TeX output of simpleexample.ok Here, what is shown is the LaTeX output created by acsdoc.rb --tolatex simplexample.ok latex simplexample.tex You can also create an HTML page by acsdoc.rb simpleexample.ok This command create a single HTML file, simpleexample.html, at the same directory as the source .ok file lives. ../examples/simpleexample.html|Here is the created HTML file. = Installation and other requirements. == Installing acsdoc Acsdoc is provided as part of the ACS software system. It can be installed as a stand-alone software. acsdoc.rb is a single Ruby source program which require no other Ruby library files or whatsoever. So you can just copy it to your preferred location. Documents are all written in acsdoc format, and can be created by make documents at the directory where the files are extracted from the archive. We plan to offer some more "packaged" way to install the command and documents. == System requirements Acsdoc has been tested on some distributions of Linux. It depends on UNIX operating system, and uses following commands/softwares * mv, rm, cp, cat, csh * convert from ImageMagick * latex, dvips * latex "subsubsection" package Dvips needs to understand options -E, -l, -x. If these options are not available with your dvips, well, you need to modify ascdoc.rb to supply appropriate options. = Running acsdoc. Syntax to invoke acsdoc is the following. % acsdoc.rb [options] [source files] infile ... Here, [options] are command line options, [source files] are name of the program source file used in listing, infile is the input text file. In the following I'll describe the meaning of command line arguments. == Input text file. Infile is the input text file. Its format is described in more details in chapter ref(sect:acsfunctionalities). One can supply multiple input files in the case of the HTML generation. For Latex, only one file can be used. The name of an input text file should end with .ok. == Source files. Source files are the files used in including partial codes. The use of them is described in sections ref(sect:includefragments) and ref(sect:includefunctions). Currently, files with extention .rb are recognized as Ruby source file, .c C program, .C and .cc C++ programs. Support on C/C++ programs is rather primitive and might not serve your need. == Options :label: options --directory dirname This option makes the generate HTML file and additional image files etc to be moved to directory +dirname+. Option argument +dirname+ must exist. If directory +dirname+ does not exist, it is created. Note that this option is ignored if --tolatex option is specified. --keep-dot-files This option is retained for backward compatibility. It has no effect. --reuseoutput This option controls if the output of inline commands (see section ref(sect:includecommand) for details) will be reused from previous run of acsdoc. If this option is not specified, all commands are newly ran on the fly. If this option is specified, and if the command appears in the same line of the text input file in the same form, the output of previous ran is reused. --tolatex Generate a Latex output instead of HTML. Default is HTML. If this option is specified with multiple text input files, the result might not correct. Latex mode is meant to be used with single input file. If you want to process multiple input files for generating single Latex file, just create one input file by using +cat+. == Output files. By default, one HTML file is created for each of one text input file. If --tolatex option is specified, one Latex file is created for one text input file, and you are not supposed to give multiple input files. There are quite a few other files generated. The image files will be stored in .imgs directory. Thus, if you have multiple input files which are processed separetely, i.e., if you do % acsdoc.rb text1.ok % acsdoc.rb text2.ok In one directory, The content of .imgs directory created in the first command is overwritten by that of the second command. To avoid this, use --directory option (see section ref(sect:options) for more details) to put output files to subdirectories. Acsdoc also create a CSS file, .acsdoc-style.css, which is referenced from HTML file. By default, the content of this CSS file is the same for any output, but it would change when the version of acsdoc.rb changes. Finaly, acsdoc creates a number of fragment files from source files specified in the command line. For example, for file foo.rb, there will be a number of files with name starting with .foo.rb (since the name of generated files start with a ".", they do not appear when you do normal +ls+ without -a option). == Examples % acsdoc.rb introduction.ok createss a single HTML file introduction.html. % acsdoc.rb -d documents introduction.ok creates a single HTML file introduction.html and store it to directory documents. % acsdoc.rb test.rb segmentsample.rb introduction.ok process the source files test.rb and segmentsample.rb to prepare fragment files used in introduction.ok, and then creates an HTML file. % acsdoc.rb introduction.ok sample.ok creates two HTML files, introduction.html sample,html, and add navigation links to these HTML files. The section (or chapter) numbers are as if these two HTML files are part of a single document. = Tour over acsdoc funtionalities. :label: acsfunctionalities Markups in acsdoc is largely similar to that of Rdoc or RD, but not exactly the same. Here we overview what is available with acsdoc. == Sections. One can start a new section (or subsection or chapter) by "=" (multiple "=" such as "==" or "===" result in deeper level, like 1.1 or 1.1.1) The following is a sample for deep sections. :include: examples/sectionssample.ok :command: cd examples; ruby ../acsdoc.rb sectionssample.ok :command: cd examples; ruby ../acsdoc.rb --tolatex sectionssample.ok :command: cd examples; latex sectionssample :command: cd examples; dvips -E -l 1 -x 1900 -o sectionssample.ps sectionssample :command: cd examples; convert sectionssample.ps sectionssample.jpeg examples/sectionssample.html|Here is the created HTML file. Up to five levels are supported, at least with HTML document. Number of levels available in Latex document depends on what is available on Latex. By default it is three. == Itemized list What you can do with

or
in HTML, or \begin{itemize} or \begin{enumerate} in Latex, you can do in a simpler way. For example, Sample list * Item 1. More text for Item 1. * Item 2 More on Item 2. gives --- Sample list * Item 1. More text for Item 1. * Item 2 More on Item 2. --- A nested list can be made in the following way Nested list * Item 1. More text for Item 1. * nested item 1 * nested item 2 * Item 2 More on Item 2. gives --- Nested list * Item 1. More text for Item 1. * nested item 1 * nested item 2 * Item 2 More on Item 2. --- Numbered list 1. Item 1 2. Item 2 gives: Numbered list 1. Item 1 2. Item 2 Note that the identifier for numbered list is numnber + ".". The number itself is not used in actual numberiing. Thus, Wrongly numbered list 1. Item 1 1. Item 2 gives Wrongly numbered list 1. Item 1 1. Item 2 == "as is" text Text lines which start with a space, where this space is not followed by *, -, or a number + ".", appear as is. Example: This is as-is text This can be used to show program list etc. == Holizontal line Three or more "-" characters --- will be converted to --- Note that it should start at first column. If any space is before "-", it becomes "as is" text. == Including file #:include: test.rb (without "#") gives: :include: test.rb Note that this is exeption for the as-is text, since this :include: directive is interpreted even when it appears with preceeding space characters. Also, space characters before the :include: directive are added to each line of the included file. Thus #:include: test.rb (without "#") gives :include: test.rb == Including program listing You can use :inccode: in place of :include:. This may shows the included text in slightly different way. Include: :include: test.rb Inccode: :inccode: test.rb In HTML, currently there is no difference. In Latex, :inccode: gives two horizontal lines marking the included code. == Including functions from source files :label: includefunctions For C/C++ or Ruby sources, an automatic way to include one function from source code is provided. In Ruby, to include the listing of function buz fom class (or module) Bar in file foo.rb, you can write ## :include: .foo.rb+buz+Bar For exaple, ":include: .acsdoc.rb+wordmarkup+Acsdoc" gives :include: .acsdoc.rb+wordmarkup+Acsdoc If +buz+ is the only function with that name in that file, or if buz is the top-level function, you can omit the class name as ## :include: .foo.rb+buz The names of source files should be given to acsdoc.rb as command-line arguments. They should appear before real .ok files in the argument list. == Including code flagments. :label: includefragments It is also possible to inclde a specified region from a source file. The region is (in the source file foo.rb) marked by "# :segment start: bar" and "# :segment end: bar" (here, bar can be some arbitrary name, without space or other special characters), and is included by ## :include: .foo.rb-bar For example, if the source file segmentsample.rb is the following: :include: segmentsample.rb By # :include: .segmentsample.rb-body We can get the following: :include: .segmentsample.rb-body == Including the output of some program :label: includecommand There are followng seven directives to run commands * :output: * :command: * :commandoutput: * :commandinput: * :commandinputoutput: * :commandinputoutputnoecho: * :commandinputoutputinteractive: and one additional directive * :prompt: The directives to run commands can have variations with "save", like * :commandoutputsave: * :commandoutputinputoutputsave: When these "save" variations are used and acsdoc is invoked with "--reuseoutput" option, acsdoc.rb look for the output of the same command previously executed (from its hidden data directory), and if the same command line is found at the same location of the input .ok file, corresponding output is taken from the saved result of previous run of acsdoc.rb. Directive :output: echo foo gives :output: echo foo Directive :commandoutput: setenv LANG C ; date :commandoutput: setenv LANG C ; date Directive :command: echo test gives nothint as output, but it is stull executed. Thus, it can be used to do whatever things you like. :command: echo test Directive :commandoutput: echo test gives :commandoutput: echo test Directive :commandinput: cat > aho END requires actual input data followed by "END", like # :commandinput: cat > aho END #aaa #bbb #ccc #END Running this (without #) shows the input and in this case create a file "aho" :commandinput: cat > aho END aaa bbb ccc END You can check if the file "aho" is made by: # :commandoutput: ls -al aho; pwd # :commandoutput: cat aho # :command: rm aho The result is: :commandoutput: ls -al aho; pwd :commandoutput: cat aho :command: rm aho Directive :commandinputoutput: cat END is similar to :commandinput:, but shows the result in text. # :commandinputoutput: cat END # aaa # bbb # ccc # END This (without #) gives you :commandinputoutput: cat END aaa bbb ccc END Finally, :prompt: xxx> changes the prompt to "xxx>". Thus, # :prompt: yebisu> # :commandoutput: echo test gives :prompt: yebisu> :commandoutput: echo test The "interactive" variant shows the input data at the location of corresponding ruby "gets". It works only with a ruby program which uses "gets" function to read input from STDIN. Here is one example: :commandinputoutputinteractivesave: ruby testinteractive.rb END 1 2 END This is made with: : commandinputoutputinteractivesave : ruby testinteractive.rb END 1 2 END The file testinteractive.rb is :inccode: testinteractive.rb == Boldface, italic, and typewriter font Boldface, italic, and typewriter font are available. This part is generated from: Boldface, italic, and typewriter font For single word (without no space), you can use a more compact form Sample *boldface*, _italic_, and +typewriter+ fonts. which will look like: Sample *Boldface*, _italic_, and +typewriter+ fonts. These markups (probably) do not work within listing. It should work with itemized list. * *boldface* in an item. == Inline tex code. Any tex code fragment can be embedded using the following form \ tex codes It can span to multiple lines. For example, Here, \$a= b$ is a sample inline tex code. gives Here, $a= b$ is a sample inline tex code. Since the use of tex codes is mostly to embed math formulae, one can write <$ tex codes$> instead of \$ tex codes $ Thus, Here, <$a= b$> is a sample inline tex code. gives Here, <$a= b$> is a sample inline tex code. == Numbered equations The following form: # :equation: # \label{equationlabel} # a=b. (without "#") gives :equation: \label{equationlabel} a=b. The texts after :equation: directive (untill a blanck line) will be processed in Latex equation environment. Equation numbers are maintained within acsdoc. Anything which can be written in Latex equation environment can be used. To refer to the above equation, you can write equation ref(equation label) which gives "equation ref(equationlabel)." The label cannot contain space. Latex eqnarray environment can be used as # :eqnarray: # \label{arrayeq} # a &=& b,\nonumber\\ # c &=&d. :eqnarray: \label{arrayeq} a &=& b,\nonumber\\ c &=&d. Note that the equation number counter of acsdoc assumes that only one number is used even when eqnarray is used. Thus, if you do # :eqnarray: # \label{arrayeq} # a &=& b,\\ # c &=&d. You get: :eqnarray: \label{arrayeq} a &=& b,\\ c &=&d. However, the next equation will have wrong number like: :equation: \label{testeq} E=mc^2. == Figures As in latex, one can make numbered figures. The syntax is # :figure: sample.gif 5cm acslogo # The ACS logo Which gives figure ref(acslogo). :figure: sample.gif 5cm acslogo The ACS logo Here, sample.gif is the name of the image file, which can have any format which is understood by "convert" command of ImageMagick. _5cm_ is the horizontal size of the image (meaningful in Latex conversion only), and _acslogo_ is the label. The text in the next and following lines, untill a blank line appear, become the figure caption. Thus, this figure can be refereed to by Figure ref (acslogo) (without space between ref and (acslogo)). Here is reference to this figure: figure ref(acslogo). Note that the size of an embedded postscript file, say foo.eps, may be too small for the html output. In such a case, you can for example double the size of the figure by converting it to a gif file, with the following command: convert -density 200x200 foo.eps foo.gif == More on references :label: moreonreferences A section (or chapter) can be labeled by the :label: directive as # :label: label For examle, this section is labeled as # :label: moreonreferences And can be referenced as # Section ref (sect:moreonreferences) is this section. Here is the output: Section ref(sect:moreonreferences) is this section. == Multiple input files When acsdoc is applied to multiple input (.ok) files, multiple HTML files (one for one .ok file) is created, but each file will have navigation links to "previous" and "next" files. The order of the files is simply the order given in the command line argument. The navigation link has "Up" entry, which by default does not point to an URL. It can be specified by setting a value in the initialization file as @@toppagefilename= "some_file_name" For example, @@toppagefilename= "../index.html" would point to index.html in the parent directory. == Table of contents The :tableofcontents: directive creates the table of contents. Example: # :tableofcontents: It should appear as only word in one line. == Links to external URLs. One can use \ tag to make links to external URL. For example, < web >http://www.artcompsci.org|ACS homepage (whithout spaces) creates a link: http://www.artcompsci.org|ACS homepage. If you specify just like \name\, it is assumed same name is specified for text and url, like acsdoc.rb, which is generated from < web >acsdoc.rb< /web > (whithout spaces). == Inline image If you want to have an inline image, you can use the form link: image_file (without space after ":"). For example, link: sample.gif gives link:sample.gif Note that "link: ..." should appear as single line without other words. Note that here the link is a direct link to the image file. Thus, if you move the generated HTML file by "--directory" option or by hand, you need to guarantee that image files are in the correct location. == Comments. Lines starting with # in the first colums are treated as comments and not further processed. # Sample comments (not shown in the processed documents) == References As in latex with natbib style file, one can make two types of citetation in the text, such as < citet >MakinoHut2006 < citep >MakinoHut2006 (without whitespaces). Actual reference entries should have the form: < REF > Aarseth, S. J. | 1963 |Aarseth1963| MNRAS, 126, 223 Makino, J.; Hut, P. | 2006 |MakinoHut2006| ACS Barnes, J. E.; Hut, P. | 1986 |BarnesHut1986|Nature, 324, 446 < /REF > Each of the reference entries consists of four fields, separated by "|". One entry can consist of multiple lines, since the separator between reference entries are two consective newlines. The first field of a reference entry is the list of authors. Authors must be separated by ";", and the familiy name, with single "," at the end, should appear first. The second field is the publication year. The third field is the tag, to be refered in the text. The 4th fieled is the actual bibiliographic data. Here is the citettion to Knuth: Knuth1992. == Examples. All of the functionalities described in this document is used in this document. So the best place to look at examples is the ch05.ok|input file itself. = Initialization file Initialization file is searched in the order of $ACSDOCINITRC, ./.acsdocinitrc, and ~/.acsdocinitrc. The things you can write in the initialization file is Ruby statement. A typical way to use is something like: # acsdoc initialization file print "Loading the initialization file for ascdoc\n" @@addtional_preambles_for_inline_tex = "\\usepackage{epsf}" @@addtional_commands_for_inline_tex = "\\input macros" This one allows the use of epsf package (style file), and macros.tex is included after \begin{document}. = Wish lists * tables = Tips == Change the document class for Latex To change the document class, supply appropriate value to variables @@basic_preambles_for_tex and @@headers in the initialization file (.acsdocinitrc). For example, @@basic_preambles_for_tex = <@@header is not used. Default is "book" class. = Known problems == tags in listing mode Most tags show themselves up correctly in listing (lines with preceeding space) mode, but \ and \ are two exeptions, at least with current (as of Nov 21 2005) version of acsdoc.rb. You need to type \\ or \\ even in listing mode. == section header just after the figure section header ( === etc) just after figure entry seems to be processed incorrectly. If you add one more newline between figure data and section header, it works fine. (May 2 2006) = Sandbox Hmm, $, ?, _ ... Are, does blank line still work as new paragraph? This should be a new paragraph. This also. This is as-is text with some tags , , , \begin{xxx} Hmm.