http://www.xs4all.nl/~apinkus/backups/
Adding a directory requires adding the directory name to various places also, in configure scripts etcerera.
CVS uses a diff-like scheme for merging differences: it looks at two text files, determines the different lines, and merges accordingly. It discovers the changes you made by looking at the version you checked out last and the version you have now, to discover which lines changed (it maintains an automatic version number for each file).
If the version of a file on your system and the version in the cvs repository has a line that has been changed by both you and some one else, the cvs repository will obviously not know what to do with that, and it will signal a 'collision' which you will have to solve by hand (don't worry, this rarely happens). More on that later.
In commands to be described in this document are in short:
To check out Yacas as anonymous user, type:
cvs -d:pserver:anonymous@cvs.yacas. sourceforge.net:/cvsroot/yacas login cvs -z3 -d:pserver:anonymous@cvs.yacas. sourceforge.net:/cvsroot/yacas co yacas |
To check out as a maintainer, type:
export CVS_RSH=ssh1 |
This will tell CVS to use ssh1 for communication. Then, in order to get yacas, type
cvs -d:ext:loginname@cvs.yacas.sourceforge. net:/cvsroot/yacas co yacas |
where loginname is your name on the sourceforge system. This then creates a directory yacas/ with the full most recent distribution. You need to enter your password there, but other than that, that's it!
Those lines typed above are long and intimidating, but it is also the last time you need to type them. From now on, if you want to do anything with cvs, just go into the yacas/ directory you just checked out, and type the cvs command without the -d... flag. This flag just tells cvs where to find the repository. But future cvs commands will know where to find them, which is why you don't need that flag.
cvs update -d |
on the command line in the yacas directory, and that should essentially download the latest version for you in that directory (just the changes). The -d option here states that you are also interested in new directories that were added to the repository. Oddly enough, cvs will only get you changed and added files, not added directories, by default.
A command
cvs -q update -d |
will print messages only about changed files.
cvs add [list of file names of ascii text files]
which adds ascii text files. If you added binary files (GIF images in the documentation directory, or something like that), you can add it with
cvs add -kb [list of file names of binary files]
Note that, when adding files to the CVS, you should normally also add them to the distribution list. This is done by adding the file name to the EXTRA_DIST variable in the file Makefile.am in the directory where you adding the file.
In case files need to be removed, there are two options:
There seems to be no easy way to rename or move files; you would have to remove them at their old location and add them at a new location.
Now, when finished with that, you might want to 'commit' all changes with
cvs commit |
If the commit succeeds, an email is sent out to the maintainers, who can then scan the diff files for changes, to see if they agree with the changes, and perhaps fix mistakes made (if any).
If there is a collision, the commit fails (it will tell you so). In case of a collision, you need to invoke cvs update twice. The cvs update outputs a list of file names with a character in front of them. The important ones are the files with a 'C' before them. They have a collision. You can go into the file, and see the collision, which the cvs system conveniently marks as:
<<<<<< old version =========== new version >>>>>> |
You can edit the file by merging the two versions by hand. This happens very rarely, but it can happen. Use cvs commit afterwards to commit.
The commit and update commands can be performed in specific directories, and on specific files, if necessary, by stating them on the command line. Or you can go into a sub directory and do a cvs commit or cvs update there, if you are confident that is the only place that changed or whose changes you are interested in.
That is basically it, a quick crash course cvs. It is actually very convenient in that usually all that is needed is a cvs commit to fix small bugs. You type that in, and your version gets merged with the changes others made, and they get your changes, and you backed up your changes at the same time (all with that little command!).
You can find more information about cvs at http://cvsbook.red-bean.com/ .
The "source" form of all documentation is maintained in a special plain text format. The format is such that it is clearly readable without any processing and is easy to edit. To compile the documents, the system processes the plain text docs with a script to prepare Yacas-language files and then runs the Yacas scripts to produce the final documentation.
The source text must be formatted in a certain fashion to delimit sections, code examples, and so on, but the format is easy enough to enter in a plain text editor. Text is marked up mostly by TAB characters, spaces, and asterisks "*" at the beginning of a line. The script txt2yacasdoc.pl converts this markup into Yacas code.
There is also a utility book2txt that attempts to convert existing documentation in the Yacas format into the plain text form suitable for txt2yacasdoc.pl. After conversion, the plain text docs normally require further editing.
Currently, documentation consists of five "books" (introductory tutorial, programming tutorial, miscellaneous essays, user's reference manual, and programmer's reference manual). The first three books are meant as stand-alone texts, while the last two are "reference" books and are meant to be used together. The Yacas Help() command will show a reference article from either of the two reference books.
Books may be divided into "chapters", "sections" and "subsections". Reference documentation contains each command description in a separate "section" which is marked by a special *CMD label (see below).
Stand-alone books are free-form, but reference books must be written with a certain template that allows online hyperlinking. The file manualmaker/in/dummies is an example template for a reference manual section.
At the beginning of each book must be a short book description (labeled *BLURB) which does not appear in printed documentation but only in the HTML top-level book index.
At the beginning of each chapter there may be a "chapter introduction" labeled *INTRO which is also a short description of the contents of that chapter. It may be one paragraph only. Note that the chapter introduction is only really useful for reference manual because it is the text that appears at the very top of a reference manual section. In the HTML version of reference docs, each chapter contains a list of all functions described in it, and this list goes right after the first paragraph of "chapter introduction". For the printed (PS/PDF) documentation the "introduction" is indistinguishable from any other text.
perl txt2yacasdoc.pl < file.txt \ > file.chapt |
In this example, file.txt contains some formatted plain text (source text) and the resulting file file.chapt will be produced in Yacas-language documentation format.
There is a single option for txt2yacasdoc:
perl txt2yacasdoc.pl -debug < file.txt \ > file.chapt |
You may want to examine the source of this file (manualmaker/ in/ YacasDocs.chapt.txt) to see how various features of the markup are used. Currently the following markup is implemented:
In> 1+2; Out> 3; |
While(x<0) [ x:=x+1; Write(x); ]; |
* Item * Another item |
* 0. First item * 0. Second item |
Note that item text continues until the next itemized line is given or until end of paragraph.
Nesting of enumerated or itemized environments is not yet supported, except for a fringe case of nesting just one itemized list at the very end of an enumerated list or vice versa.
Enumerated environment is currently only implemented in LaTeX docs; HTML docs render them as itemized.
<*http://host.net/file.html#anchor*> |
<*click here|somewebpage.html*> |
Mathematical expressions must be valid Yacas expressions, with balanced parentheses, no hanging periods and so on, or else the Yacas script that formats the docs will fail! (This limits the scope of mathematical formulae but is hopefully not critical.) Currently, when creating online HTML documentation, mathematics is kept in Yacas notation and set in boldface font. (This may change in the future.) Of course, LaTeX typesets printed documentation with correct mathematical symbols.
Another feature of the LaTeX exporter is that it will try to show all functions and infix operators according to their mathematical meaning, and if no such meaning is defined in Yacas, then it will show them exactly as they are written in Yacas. For infix operators to work, they have to be declared in the standard library, or else an error will occur when processing the manual. For example, Yacas operators = and == are both represented by and equals sign "=", the operator := becomes "identically equal" ( a:=b), and the cosmetic operators <> and <=> become a<>b and a<=>b. But you cannot use an undefined infix operator such as ":=*".
*INCLUDE ../essays/howto.chapt |
Note that the included document must be a Yacas-language file. (This will become the IncludeFile() call in the Yacas document -- an alias to Load().)
The additional elements all start with an asterisk "*" in the first position on a line, followed by an uppercase keyword. A typical reference manual subsection documenting a certain function may look like this in plain text:
*CMD PrintList --- print list with padding *STDLIB *CALL {PrintList}(list) {PrintList}(list, padding); *PARMS {list} -- a list to be printed {padding} -- (optional) a string *DESC Prints {list} and inserts the {padding} ... *E.G. In> PrintList({a,b,{c, d}}, " .. ") Out> " a .. b .. { c .. d}"; *SEE Write, WriteString |
Notes:
In a subsection there may be either one function documented or several at once: for example, it may make sense to document Sin, Cos and Tan together. In this case, all function names should be simply listed in the *CMD header, for example:
*CMD Sin, Cos, Tan --- Trigonometric ... |
In addition, there is a tag *INTRO to denote a "reference chapter introduction" corresponding to the ChapterIntro() function, *BLURB for book introduction (only enters the HTML book index but not LaTeX docs), *A which creates an HTML link to a manual section corresponding to AddBody(HtmlAnchor()...), *AA which creates AddAnchor(), and *HEAD which creates a small heading (Topical()). For instance,
*PARMS |
*HEAD Parameters: |
The *INTRO and *BLURB tags only work for one paragraph. There must be no empty line between *INTRO/*BLURB and that paragraph. Also, there must be no empty line between the "blurb" and the book title (for technical reasons). There must be one and only one "blurb" paragraph in a "book" and no more than one "chapter intro" paragraph per chapter.
This markup should be sufficient for creating reference documentation in plain text.
If a manual book does not compile after you made some changes, examine the Yacas-language files (*.chapt, *.book), find the line at which an error occurred, and try to see what happened. Most probable cause of error is unbalanced brackets, parentheses, or dollar signs; or expressions which should not be split between lines were accidentally split after reformatting the text. Mathematical expressions cannot contain a trailing period (e.g. you cannot say $x+a.$ -- the period should go outside dollar signs.
(Note: as of version 1.0.49, all Yacas documentation is converted to plaintext format. This section is left for reference only.)
By using a command such as
book2txt.sh file.chapt |
12:51pm scriabin> book2txt.sh intro.book [editvi.ys] [gnuplot.ys] True; Out> True; Quitting... File 'intro.book.txt' was created. 12:51pm scriabin> |
In the above example, the shell commands in book2txt.sh executed the following Yacas commands,
Use("book2txt.ys"); ToFile("file.chapt.txt") Load("file.chapt"); |
Of course, it is possible that some features of Yacas documentation were not implemented in the script and in that case the resulting file must be edited by hand. But the purpose of the book2txt script is exactly this: to make a plain text source file to be edited and maintained.
Several files can be converted at once, for example:
book2txt.sh f1.chapt f2.chapt file3.book |
book2TeX.sh intro.book intro.book.tex |
latex intro.book.tex latex intro.book.tex dvips -o intro.book.ps intro.book dvi |
latex intro.book.tex pdflatex intro.book.tex |
The shell commands in book2txt.sh execute the following Yacas commands:
Use("book2TeX.ys"); ToFile("file.chapt.tex") Load("file.chapt"); |
Not all features of Yacas documentation are compatible with TeX typesetting. To prevent errors, documentation should avoid certain things. In general, it is a good idea to check the typeset appearance of documentation, since it helps detect errors.
For example, the symbols %, { }, < >, #, \, _ and & are special to TeX. They should not normally be used in plain text; it is okay to use them in "typerwriter" text or code samples -- but not in section or chapter heads, because it makes it difficult to export to TeX correctly. TeX commands may be entered but will not be correctly rendered in HTML online documentation. Sometimes fixed-font text will hang over the right edge; a workaround is to break the fixed-font text into shorter fragments or to rephrase the text.
Another concern is that code examples are typeset in a fixed-width font and may not fit into the width of the page and will be hanging over it. To avoid this, the code in the code examples should not be longer than about 44 characters.
The current implementation uses a "report" style which allows chapters, sections, subsections and includes an automatically generated table of contents. ( LaTeX is automatically run twice to produce the TOC when executing make texdocs.)
Some complicated mathematical expressions may not correctly render in TeX. This is because Yacas uses its internal function TeXForm() to transform Yacas expressions to TeX. Mathematical expressions are entered in the plain text documentation source using Yacas syntax, then transformed to a special non-evaluating call TeXMath() in the Yacas-language documentation, which formats into HTML using a Write() call or into TeX using a TeXForm() call, as necessary. Testing should be performed on documentation before releasing it. The most stringent limitation is that the expression between dollar signs should evaluate in Yacas (perhaps to itself) and not cause syntax errors. In case of doubt, try whether the expression evaluates without errors and then try to use TeXForm on that expression and see if that evaluates without errors.