Previous ToC Up Next

# Contents

## 4. 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.

## 5. Simple Example

The following is a simple example.

  = Simple Example

This is a simple example.


This one creates the output shown in figure
1

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.

Here is the created HTML file.

## 6.1. 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.

## 6.2. 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.

## 7. 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.

## 7.1. Input text file.

Infile is the input text file. Its format is described in more details in chapter 8. 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.

## 7.2. Source files.

Source files are the files used in including partial codes. The use of them is described in sections 8.8 and 8.7. 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.

## 7.3. Options

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 8.9 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.

## 7.4. 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
7.3 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).

## 7.5. 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.

## 8.1. 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.

  = First level section

This must be section 1

== 2nd level section

Here is section 1.1

=== 3rd level section

Here is section 1.1.1

= More sections

Here is section 2.


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.

## 8.2. Itemized list

What you can do with

  <ul> or <ol>

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
2. Item 2

## 8.3. "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.

## 8.4. 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.

## 8.5. Including file

  #:include: test.rb

(without "#") gives:

  ## test.rb
def test
p test
end
test


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

               ## test.rb
def test
p test
end
test


## 8.6. Including program listing

You can use :inccode: in place of :include:. This may shows the included text in slightly different way.

Include:

  ## test.rb
def test
p test
end
test


Inccode:

  ## test.rb
def test
p test
end
test


In HTML, currently there is no difference. In Latex, :inccode: gives two horizontal lines marking the included code.

## 8.7. Including functions from source files

  ##  :include: .foo.rb+buz+Bar

For exaple, ":include: .acsdoc.rb+wordmarkup+Acsdoc" gives

   def wordmarkup(instr)
@@wordreplace.each do |x| instr.gsub!(x[0]) do |word|
$1 + x[1]+ " " +$2 +x[2] + $3 end end instr end  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. ## 8.8. Including code flagments. 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:  class Test def test p "test called" end end # :segment start: body a= Test.new a.test # :segment end: body  By  # :include: .segmentsample.rb-body  We can get the following:  a= Test.new a.test  ## 8.9. Including the output of some program and one additional directive • :prompt: The directives to run commands can have variations with "save", like • :commandoutput: • :commandoutputinputoutput: 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  foo  Directive :commandoutput: setenv LANG C ; date  |gravity> setenv LANG C ; date Thu Sep 13 23:07:21 JST 2007  Directive :command: echo test gives nothint as output, but it is stull executed. Thus, it can be used to do whatever things you like. Directive :commandoutput: echo test gives  |gravity> echo test 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" You can check if the file "aho" is made by:  # :commandoutput: ls -al aho; pwd # :commandoutput: cat aho # :command: rm aho  The result is:  |gravity> ls -al aho; pwd -rw-r--r-- 1 makino makino 12 Sep 13 23:07 aho /home2/makino/acs/kali/vol/documentation |gravity> cat aho aaa bbb ccc  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  |gravity> cat aaa bbb ccc aaa bbb ccc  Finally, :prompt: xxx> changes the prompt to "xxx>". Thus,  # :prompt: yebisu> # :commandoutput: echo test  gives  yebisu>echo test 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:  yebisu>ruby testinteractive.rb enter x:1 enter y:2 1.0 2.0  This is made with:  : commandinputoutputinteractivesave : ruby testinteractive.rb END 1 2 END  The file testinteractive.rb is  STDERR.print "enter x:"; x =gets.chomp.to_f STDERR.print "enter y:"; y =gets.chomp.to_f print x, " " print y  ## 8.10. Boldface, italic, and typewriter font Boldface, italic, and typewriter font are available. This part is generated from:  <b>Boldface</b>, <em>italic</em>, and <tt>typewriter font</tt>  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. ## 8.11. Inline tex code. Any tex code fragment can be embedded using the following form  <tex> tex codes </tex>  It can span to multiple lines. For example,  Here, <tex>$a= b$</tex> is a sample inline tex code.  gives Here, 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>$ tex codes $</tex>  Thus,  Here, <$a= b$> is a sample inline tex code.  gives Here, is a sample inline tex code. ## 8.12. Numbered equations The following form:  # :equation: # \label{equationlabel} # a=b.  (without "#") gives 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 1." The label cannot contain space. Latex eqnarray environment can be used as  # :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: However, the next equation will have wrong number like: ## 8.13. Figures As in latex, one can make numbered figures. The syntax is  # :figure: sample.gif 5cm acslogo # The ACS logo  Which gives figure 2. 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 2. 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  ## 8.14. More on references  # :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 8.14 is this section. ## 8.15. 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. ## 8.16. Table of contents The :tableofcontents: directive creates the table of contents. Example:  # :tableofcontents:  It should appear as only word in one line. ## 8.17. Links to external URLs. One can use <web> tag to make links to external URL. For example,  < web >http://www.artcompsci.org|ACS homepage</web>  (whithout spaces) creates a link: ACS homepage. If you specify just like <web>name</web>, it is assumed same name is specified for text and url, like acsdoc.rb, which is generated from  < web >acsdoc.rb< /web >  (whithout spaces). ## 8.18. 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 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. ## 8.19. Comments. Lines starting with # in the first colums are treated as comments and not further processed. ## 8.20. References As in latex with natbib style file, one can make two types of citetation in the text, such as  < citet >MakinoHut2006</ citet> < citep >MakinoHut2006</ citep>  (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: Knuth(1992). ## 8.21. Examples. ## 9. 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}.

• tables

## 11.1. 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 = <<END
\\documentclass{article}
\\usepackage{graphicx}
END
@@header=[
"chapter","section","subsection","subsubsection",
"subsubsubsection", "subsubsubsubsection"]

is appropriate for article class. First item of @@header is not used. Default is "book" class.

## 12.1. tags in listing mode

Most tags show themselves up correctly in listing (lines with preceeding space) mode, but

 <tex>

and
 <web>

are two exeptions, at least with current (as of Nov 21 2005) version of acsdoc.rb. You need to type
 \<tex>

or
 \<web>

even in listing mode.

## 12.2. 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)

## 13. 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 <xxx>, <tt>, <b>, \begin{xxx}

Hmm.
 Previous ToC Up Next