File: YacasDocs.chapt.txt

package info (click to toggle)
yacas 1.3.6-2
  • links: PTS
  • area: main
  • in suites: bullseye, buster, sid, stretch
  • size: 7,176 kB
  • ctags: 3,520
  • sloc: cpp: 13,960; java: 12,602; sh: 11,401; makefile: 552; perl: 517; ansic: 381
file content (857 lines) | stat: -rw-r--r-- 47,817 bytes parent folder | download | duplicates (5)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
		Preparing and maintaining Yacas documentation

	    Introduction

*A documentation
Yacas documentation in HTML and PS/PDF formats is generated by Yacas scripts from Yacas source files.
Prior to version 1.0.48, all documentation had to be written directly in the Yacas language.
However, it was very cumbersome to write those source files in the Yacas language.
The scripts {txt2yacasdoc.pl},
{book2TeX.sh}, {book2ys.sh}, {ytxt2tex}
were created to help maintain the documentation in an easy-to-read form.

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 other scripts to produce the final documentation in HTML and other formats.

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 format is easy enough so that, for example, the text of the GNU GPL (the file {COPYING}) can be used as a documentation source file without changes.
The script {txt2yacasdoc.pl} converts this markup into Yacas code for further processing.

	    Organization of the Yacas documentation

*A documentation!organization
All documentation source files are kept in the subdirectory {manmake}.
During compilation, Yacas language files as well as HTML, $LaTeX$ and PS/PDF
files are automatically generated in the {manmake} subdirectory.
Contributors should only need to edit {*.txt} files in {manmake}.

Currently, the Yacas documentation consists of four "core" books (the introductory tutorial,
the programming tutorial, the user's reference manual, and the
programmer's reference manual), and three "extra" books (algorithms, Lisp programming, essays).
*FOOT There is also a documentation book describing the Emacs interface to Yacas (the "Yacas Notebook" mode). This book is not available as online help but is installed separately in the TeXinfo or PostScript formats.

All Yacas documentation books are distributed under the GNU Free Documentation License (FDL).
If you add a new documentation book to Yacas, please include the file {FDL.chapt}.

The documentation books are meant to be stand-alone
texts, except the two "reference manual" books which are meant to be used
together because they share a common hyperlinked table of contents.

Stand-alone books are free-form, but reference books must be written with a
certain template that allows online hyperlinking. The file
{manmake/dummies} is an example template for a reference manual section.

Books are divided into "chapters", "sections" and "subsections".
The reference manuals
contain descriptions of Yacas commands and functions,
and each function is given in a separate (unnumbered) section which
is marked by a special {*CMD} label (see below). 

At the beginning of each book there <i>must</i> be a book title and a short book description (labeled {*BLURB}).
The short description appears in the printed version as the subtitle on the title page.
It also goes into the HTML top-level book index as the book description.

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. The "chapter intro" feature is only
used in the HTML reference manual because it is the text that appears at the very top
of a reference manual section. As you can see in the HTML version of reference docs, each
chapter contains a list of all functions described in it. This list goes
right after the first paragraph of "chapter intro".
In the printed (PS/PDF) documentation, the {*INTRO} label is ignored and the "chapter intro" paragraph is shown exactly like any other text paragraph.

Each printed book contains a table of contents at the beginning and an index at the end.
The index should help a reader to quickly find a particular concept.
For example, all documented Yacas commands are automatically entered into the index in the reference manual.
Additional index entries should be inserted by hand using the {*A} label (see below).

	    Translating the documentation

The Yacas system is under active development and its documentation is constantly updated.
An effort to translate the Yacas documentation from English into other languages has been started.

Translators should try to prepare translated documentation in the same plain text format as the original documentation.
Any problems with conversion to HTML and PS/PDF formats should be easy to solve (at least for European languages).

The most important documentation books to translate are the reference manual and the tutorials.
There is substantial documentation aimed at developers, for instance the algorithms book or the essays book.
It is probably not as important to translate such books, since Yacas developers have to speak English to communicate.


	    Formatting of source text files

*A documentation!markup overview
Formatting of source text files uses TAB symbols; if your editor does not support them and converts them to spaces, you should convert the results back to contain real TAB symbols using the standard Unix {unexpand} utility or a custom perl script.

You may want to examine the source of this file ({manmake/}
{YacasDocs.chapt.txt}) to see how various features of the markup are used.
Currently the following markup is implemented:

*	Paragraphs are separated by blank lines (lines consisting of space characters or empty). Several blank lines next to each other are equivalent to one. However, TAB-indented blank lines inside a code example (see below) do not create another paragraph.

*	Book heading is quadruple TAB indented. Chapter heading is triple TAB indented. Section heading is double TAB indented. Subsection heading is indented by a TAB and 4 spaces. Headings must be within one line (but that line can be as long as needed).

*	Sample code is single TAB indented, for example:
	In> 1+2;
	
	Out> 3;
Note that empty lines in a single sample code block must be also TAB indented
or else the sample code block will be split into several sample code
paragraphs.
A sample code block may or may not be separated from the text that follows
it by an empty line.
If the code block is not separated by an empty line, then the text following it will not be made
into a separate paragraph (this currently affects paragraph indentation only in
PS/PDF docs).

*	If a section or chapter heading immediately follows a sample code block
(i.e. when it is the last code sample in the previous section), they
<i>must</i> be separated from the headings by an empty (unindented) line. The
reason for this is that the script will assume that everything which is at
least single-TAB indented (up to a separation between paragraphs) belongs to
one sample code block. This makes it easier to enter multiply indented sample
code: a double-TAB indentation inside a sample code block will not start a new
section. For example:
	While(x<0) [
		x:=x+1;
		Write(x);
	];

*A documentation!environments
*	Ordinary text must not be indented at all. Line length is arbitrary and
linebreaks
inside
a
paragraph
are of no significance to the resulting documentation. The first symbol on a
line should not be an asterisk ({*}) because it is reserved for markup
purposes. In most cases it is okay to have an asterisk in the first position,
though, as long as it does not conflict with any markup labels (see below).
All markup labels start with an asterisk "{*}" in the first position on
a line, followed by an uppercase keyword, e.g. {*CMD} or *{INCLUDE}.
Some markup labels have arguments that follow them, and some take an
entire following paragraph as an argument and must be terminated by a
blank line.

*	Itemized text is marked by "*" in the first position, followed by TAB. For example:

	*	Item
	*	Another item
This will produce:
*	Item
*	Another item

*	Enumerated text is marked by "*" followed by TAB, number and period. The number used in the source text is irrelevant because the enumerated environment of the final document will introduce its own counter. For example:
	*	0. First item
	*	0. Second item
This will produce:
*	0. First item
*	0. Second item

Note that the text of an item continues until the next itemized line is given or until end of paragraph (does not have to be all in one line).

Nesting of enumerated or itemized environments is not supported, except for fringe cases of nesting just one itemized list at the very end of an enumerated list or vice versa.

The enumerated environment is currently only implemented in $LaTeX$ docs; HTML docs render them as itemized.

*A documentation!fonts
*	Emphasized text (<i>italics</i>) should be surrounded by {<i>}
{</i>}. Note that the whole emphasized fragment of text must be located within a single line, or else it will not be emphasized.

*	{Typewriter font} text is surrounded by braces {{}}. The typewriter font
fragment must be within a single line and may contain no more than four nested
sets of {{}} inside. This is hopefully enough for our documentation. A
limitation of this markup is that there is no way to put a single brace in text
alone without a matching brace. This would be okay for HTML docs but it breaks
$LaTeX$ docs because braces are special in $TeX$ and because Serge was too lazy
to implement a real parser.

*A documentation!Web hyperlinks
*	Web hyperlinks are surrounded by {<*}
{*>}. Text of the link must begin with {http://}, {https://} or {ftp://}. Alternatively, a hyperlink with anchored text is made by the markup {<*}
<i>anchored text</i> {|}<i>Web URL</i>{*>}. For example:
	<*http://host.net/file.html#anchor*>
or
	<*click here|somewebpage.html*>
(the latter example will refer to a local HTML file, i.e. a file in the documentation directory).

Note: Currently, only the HTML documentation is hyperlinked, while the printed PS/PDF documentation contains only text.

*A documentation!internal hyperlinks
*	It is also possible to create hyperlinks pointing to other parts of the documentation.
Such "documentation hyperlinks" are similar to the Web hyperlinks, except they use a special "protocol" named {yacasdoc} and chapters and sections can be referred to as "subdirectories".
For example, this section can be referred to by the following code:
	<*yacasdoc://essays/5/2/*>
A hyperlink with anchored text is made by the markup {<*}
<i>anchored text</i> {|}yacasdoc://...{*>}. For example:
	<*this section|yacasdoc://essays/5/2/*>
will generate a reference to <*this section|yacasdoc://essays/5/2/*> in the documentation.
There are currently the following ways to create documentation hyperlinks:
*	0. Hyperlink into an anchor of the same file:
	<*yacasdoc://#documentation!hyperlinks*>
The anchor "{documentation}{!}{hyperlinks}" should have been created using the {*A} label.
*	0. Hyperlink into an anchor in a different documentation book:
	<*yacasdoc://Algo/3/#adaptive plotting*>
Note that one must specify the book name "{Algo}" and the chapter number ({3}) for this to work. Currently supported book names are {Algo}, {coding}, {essays}, {intro}, {Lisp}, {ref}, and {refprog}. A warning message is printed if the book name is not given correctly.
*	0. Hyperlink into a given chapter or a given section of a documentation book:
	<*yacasdoc://Algo/3/1/*>

*A documentation!equations
*	Mathematical expressions should be typed in {Yacas} syntax (<i>not</i> in $TeX$
notation) and surrounded by dollar signs.
Both delimiting dollar signs
<i>must</i> be within one line of text.
For example: {$}
{x^2 + y^2 != z^2 $}
produces $x^2+y^2 != z^2$. Double dollar signs will denote a displayed
equation, like in $TeX$; both pairs of dollar signs should still be within one
line.

There is a special feature for displayed equations:
Any punctuation immediately following the second pair of dollar signs will be displayed on the same line. (This is used to get around the limitation of mathematical expressions that cannot end with a comma or a period or with another punctuation mark.) For example, the formula "{$}{$}{x^2/2}{$}{$,}" will produce $$x^2/2$$, with the comma on the same line. A formula such as "{$}x+1;{$}" will generate an error; the semicolon should be moved out of the dollar signs.

As special exceptions, one can enter the symbols "$TeX$" and "$LaTeX$"
as if they are Yacas expressions, i.e. "{$T}{eX$}" produces "$TeX$". One can also create a capitalized form of the name {Yacas} as "{{Yacas}}".

Please note: Mathematical expressions <i>must</i> be <i>valid Yacas expressions</i>, with no unbalanced
parentheses, no undefined infix operators, 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.)

Also, please avoid putting equations into documentation as plain text. Expressions such as $a>0$ are not correctly typeset by $TeX$ if included into the plain text without the dollar signs: "a>0". (The HTML documentation is currently not affected.)

Currently, when creating online HTML documentation, all
mathematics is kept in Yacas notation and set in boldface font. (This may
change in the future.)
Of course, $LaTeX$ typesets the documentation with
correct mathematical symbols.

Another feature of the $LaTeX$ exporter is that it will first try to represent 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, the Yacas operators {=} and {==} are represented in $LaTeX$ by an 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
infix operator such as "{:=*}" because it is not defined in the standard library. A Yacas function which is not defined in the standard library, for example "{func(x)}", will appear just like that: $func(x)$.

*A documentation!insert another file
*	Documentation may be split between several files for convenience.
To insert another file, use the {*INCLUDE} label, e.g.

	*INCLUDE ../essays/howto.chapt

Note that the included document is the file {howto.chapt}, not {howto.chapt.txt},
because it must be a Yacas-language file, not a {.txt} file.
(The {IncludeFile()} call, an alias to {Load()}, will be used
to execute the specified file.)

*A documentation!comments
*	Comments may be introduced by the label {*REM}. The line and the paragraph of text following {*REM} will be omitted from the documentation.
An empty line should separate the {*REM} block from other text.
(A mark-up label at the beginning of line will also terminate a {*REM} block.)
For example,
	*REM this is
	a comment
	
	(documentation text continues)

*A documentation!footnotes
*	Footnotes may be entered as a line containing the label {*FOOT}. Footnote text must be within one line (because a footnote does not necessarily break a paragraph).

For example, the text
	*FOOT This is an example footnote
generates the footnote
*FOOT This is an example footnote.

*	Yacas expressions may be evaluated inline by using the directive {*EVAL}. Anything that follows {*EVAL} until the end of the line will be evaluated as a Yacas expression. If this expression prints something (e.g. via {Write}), the output will be inserted into the text (as is). The resulting value of the expression will also be inserted, unless the expression evaluates to {True}. The Yacas expression <i>must</i> be on one line.

For example,
	*EVAL "Yacas version: " : Version()
will insert the string `
*EVAL "Yacas version: " : Version()
' into the manual. Note the spaces around the version string---these additional spaces are currently unavoidable.
*FOOT If the absence of spaces is critically important, you can create the required text in a Yacas expression.

	    Formatting conventions for the reference manual

*A documentation!reference manual markup
The formatting explained in the previous section is enough to create most of the user guide and tutorial documentation. The script {txt2yacasdoc.pl} also implements some additional markup features to help create the reference manual.

A typical reference manual subsection documenting a certain function may look like this in plain text:

	*CMD PrintList --- print list with padding
	*STD
	*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
Compare this with the reference manual section on the function {PrintList} to see how this plain text markup is rendered in the finished documentation.

Notes:
*	Some labels have parameters while other labels do not; labels that do not have parameters must be put alone on a line.
*	The {*STD} label is for functions defined in the standard library and the {*CORE} label is for built-in functions defined in the Yacas core engine.
In addition, the labels {*UNIX}, {*MSWIN} and {*MAC} can be used to denote Un*x, MS Wind*ws and Macint*sh-specific add-on functions.
*	There must be <i>some</i> whitespace separating a markup label such as {*SEE} and the following text.
Either TAB characters or spaces work equally well.
*	The comma-space combination "{, }" is mandatory when a label accepts a list of arguments.
(One can put several spaces after a comma.)
Lists of commands are used by the {*CMD} and {*SEE} labels.
*	Characters {<} and {>} are of special significance to both HTML and $TeX$ and should be always escaped---either by braces {{}} or by dollar signs, as appropriate.
*	In the "examples" section, there may be just one example, in which case the alternative label "{*EG}" could be used instead of "{*E.G.}". This will currently generate the word "Example:" instead of "Examples:" in the documentation.
(This is a cosmetic feature.)
*	Each example is a candidate for inclusion into the Yacas test suite.
The Yacas code after the {In>} prompts and the resulting expressions that follow the {Out>} prompt are extracted into special files by the script {txt2example.pl}.
(This provides an automatic check that the manual still agrees with the actual behavior of Yacas.)
The script will ignore any text that is not preceded by {In>} or {Out>}.
However, some examples are not appropriate for automatic testing and must be explicitly excluded.
An example section is excluded for testing if the {*E.G.} or {*EG} label is followed by the word "notest", for example:
	*EG notest
		// some advanced tests
Tests may be unsuitable for automatic processing for several reasons, including:
system-dependent results (e.g. need to have particular files on the system); calculations that take a long time; calculations that output something to the screen and not just return an expression.
*	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 to the above labels, there are the following tags:

*	{*INTRO} to denote a "reference chapter
introduction" corresponding to the {ChapterIntro()} function
*	{*BLURB} for the short book
summary (it enters the HTML book index and the front page of the $LaTeX$ docs)
*	 {*A} to manually
create an HTML anchor in a reference manual section and an index entry in the printed docs (see below for more details on indexing)
*	{*HEAD}
to create a small heading.
The {*HEAD} tag might be useful for lowest-level headings.
Currently, the special markup for the reference manual implements the same tag for its topical sections ("Parameters", "See also" etc.) {*HEAD}.
For instance,
	*PARMS
results in the same text as
	*HEAD Parameters:

Usage of the {*A} label currently does not directly affect the appearance
of the docs.
In the HTML docs, it inserts the insivible anchor tags {<a></a>}.
In the printed $LaTeX$ docs, the {*A} label adds an index entry.
The {*CMD} tag generates all necessary HTML anchors and index entries for
commands in the reference manual.
So only non-command index entries need to be manually entered using {*A}.

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.

	    Indexing the documentation books

*A documentation!indexing

It is not difficult to automatically generate an alphabetically sorted
index for the books. An "index entry" is a piece of text that does not
appear in the book where it is entered, but instead is printed in the
alphabetical list at the end of the text with the relevant page number.

Currently the following facilities are provided for indexing:

*	1. The label {*CMD} automatically adds index entries for all commands it describes. In this way, the printed reference manual automatically has every documented command listed in the index.
*	2. The label {*A} can be used to add an index entry by hand. An index entry can be any text that is admissible in the documentation (on one line). Preferably it should be something concise and something that users will want to look up and can't easily locate in the table of contents.

After $LaTeX$ generates a "raw" index file {*.idx}, the {makeindex}
utility is used to post-process and sort the index into the {.ind}
file. If you do not have {makeindex} on your system, the book indices
will not be generated.

Note that {makeindex} is not always friendly to special
(non-alphanumeric) characters. For example, it uses the symbol {!} to
separate index topics, which may conflict with Yacas commands. In other
words, document index must be tested and sometimes debugged.

In the HTML docs, the index is currently not generated on a separate
page, although HTML anchors are inserted in the text. 

An index entry may be a "topic" with "subtopics", which usually appears in book indices like this:
	gnus, 51
	   tame, 51
	   wild, 52-341
This effect can be achieved with the {!} topic separator:
	*A gnus
	*A gnus!tame
	*A gnus!wild
This is a special feature of {makeindex}.

Currently, it is possible to include a command or an equation into an index entry, for example,
	*A {InterestingCommand}
	*A calculation of $Sqrt(x)$
But this may sometimes conflict with the topic separator.

	    Summary of mark-up labels

*A documentation!summary of labels

Mark-up labels <i>must</i> appear as first characters on a line. The following mark-up labels are currently defined:


Labels with an argument on the same line (affect only the current line):

*	{*A} <i>anchor</i> -- insert anchor and index entry
*	{*BOOK} <i>title</i> -- start a book, give title
*	{*EVAL} <i>statement</i> -- evaluate inline as a {Yacas} statement and insert results
*	{*HEAD} <i>heading</i> -- lowest-level heading (lower than subsection)
*	{*FOOT} <i>text</i> -- insert a footnote
*	{*INCLUDE} <i>filename</i> -- include another documentation file
*	{*YSFILE} <i>filename</i> -- give an alternative file name for {Yacas} code extraction (see the section on {book2ys})

Labels that affect the rest of the line and the subsequent paragraph:

*	{*BLURB} -- short summary of the book (must immediately precede the {*BOOK} label without any empty lines)
*	{*INTRO} -- chapter introduction (significant for HTML only) (must be separated by an empty line from what follows)
*	{*REM} -- documentation comment (must be separated by an empty line from what follows)

Special labels for the reference manual that accept several arguments on the same line:

*	{*CMD} or {*FUNC} -- command name and one-line description
*	{*SEE} -- "See also"

Special labels without arguments that generate headings for the reference manual:

*	{*STD} -- "Standard library"
*	{*UNIX} -- "Unix-specific"
*	{*MSWIN} -- "MS Windows-specific"
*	{*MAC} -- "Macintosh-specific"
*	{*CORE} -- "Core function"
*	{*CALL} -- "Calling format"
*	{*PARMS} -- "Parameters"
*	{*DESC} -- "Description"
*	{*E.G.} -- "Examples"
*	{*EG} -- "Example"

Other special markup:

*	{*BREAK} -- insert an explicit line break at this point (no new paragraph)
*	{*NEWPAGE} -- start a new page at this point ($LaTeX$ documentation only)
*	{<*}
... {*>} -- insert a hyperlink

	    Summary of special markup syntax

*A documentation!summary of syntax

Special syntax entities include:
*	TAB indented: book title (4 TABs), chapter (3 TABs), section (2 TABs), subsection (1 TAB and 4 spaces) titles, sample code (1 TAB)
*	asterisk-TAB: enumerated environment
*	asterisk-TAB-number-period: itemized environment
*	curly braces
"{{}}": inline code samples, names of functions or variables (monospaced font)
*	special delimiters
"{<i>}"
and "{</i>}": italics (for emphasis, not for mathematics).
Both delimiters must be on the same line.
*	dollar signs "{$}", "{$}{$}": inline and displayed mathematical equations
*	special delimiters
"{<*}" and
"{*>}": Web hyperlinks and documentation hyperlinks.
Both delimiters must be on the same line.
*	the exclamation mark
"{!}": nested index entries (use inside the {*A} label)

	    Debugging the manual

*A documentation!markup debugging
Sometimes the manual compilation {make} or {make texdocs} will break after you edit the plaintext manual sources. This can happen for one of these reasons:
*	1. A math syntax error. You have used a mathematical formula that does not evaluate to a Yacas expression. Unbalanced parentheses, invalid infix operators such as {>-}, {=-}, or forgotten punctuation inside the formula such as {x+1:} are the most frequent culprits. This will break both HTML and $TeX$ manual formats.
*	2. The HTML format compiles but the $TeX$ does not (the {latex} commands never finishes, that is, $latex$ prints an error message which you do not see because it is redirected to {/dev/null}, and waits for your input; you have to kill the process).
This means that somewhere the generated $TeX$ code is incorrect. You probably forgot to balance braces {{}} or something more subtle happened.
*	3. Some mark-up which should not be split between lines was
unintentionally split by reformatting paragraphs in a text editor. This will sometimes not break the compilation but will always give undesired results.

In case of a math syntax error, the documentation exporter cannot print the paragraph where the error occurred, but it usually prints the preceding paragraph. Currently, the easiest way to locate the error is to generate the {.tex} output and look at it, e.g.:
	make ref.book.tex; less ref.book.tex
The last line in the {.tex} file must be {\end{document}}. If it is not, then the last portion of the text you see in the {.tex} file is the text directly before the paragraph where the error occurred. Most probably, there is a malformatted math formula in the next paragraph of your plaintext source.

If the last line is  {\end{document}} but {latex} does not finish, you will have to run {latex} by hand, e.g.
	latex ref.book.tex
and look at the error message(s) it prints.

	    Using the script {txt2yacasdoc.pl}

The script {txt2yacasdoc.pl} is used to transform plain text markup into the
Yacas language. The script acts as a stream filter:

	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
This option is to be used for debugging, i.e. when the resulting file does not
compile in Yacas. The effect of this option is to introduce more breaks
between text strings in the generated file, so that the {Text()} function is
called more often. It is then easier to locate the source of the problem in the
Yacas-language file (Yacas will tell you the last line in the Yacas-language
file at which a syntax error occurred). This option is largely obsolete because
the {Text()} function is called frequently enough by default.
See below for hints about finding syntax errors in documentation when the manual does not compile.


	    {book2TeX}: preparing typeset documentation

The script {book2TeX.sh} prepares a $TeX$ file out of a Yacas-language documentation book. Usage is similar to {book2txt.sh}, except that only one file is processed at a time and the file must be a "book", not just a "chapter". For example:
	book2TeX.sh intro.book intro.book.tex
will create a $LaTeX$-formatted version of the introductory tutorial.
The $LaTeX$ file can be processed with standard tools, for example
	latex intro.book.tex
	dvips -o intro.book.ps intro.book dvi
will prepare a Postscript version, while
	pdflatex intro.book.tex
will prepare a PDF version.

To generate printed docs, it is necessary to run {latex} (at least)
three times in a row. This is because at first {latex} does not know
how much space will be taken by the table of contents and the index, so
the page numbers are all off by a few pages. Only on the second run
{latex} generates correct page numbers for the TOC (the {.aux} file)
and for the index (the {.idx} file). After this the index file has to
be processed by the {makeindex} routine to sort it, and the third
{latex} run is needed to actually insert the correct TOC and the
processed index into the final document.

The shell commands in {book2txt.sh} execute the following Yacas commands:
	Use("book2TeX.ys");
	ToFile("file.chapt.tex")
	  Load("file.chapt");
This requires that the Yacas script {book2TeX.ys} be available in the current directory. The shell script {book2TeX.sh} assumes that {book2TeX.ys} is stored in the same directory as {book2TeX.sh} and that the Yacas executable is available in the directory {../src/}. Alternatively, the command line of the Yacas executable can be specified by the {-run} option. For example, the {Makefile} runs {book2TeX.sh} like this:
	book2TeX.sh -run "yacas-dir/src/yacas --rootdir
	  yacas-dir/scripts" file.book file.book.tex
Note that the entire Yacas command line is given in quotes.

*HEAD Some concerns with the printed documentation

*A documentation!$TeX$ problems
Not all features of the Yacas documentation-generating scripts are compatible with $TeX$ typesetting. To prevent errors, documentation source 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 "typewriter" text (within braces {{}}) or code samples -- but <i>not</i> 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.

*A documentation!lines too wide
Sometimes fixed-font text will hang over the right edge of the printed
page. A workaround is to break the fixed-font text into shorter
fragments or to rephrase the text.

Another concern is that code examples (TAB-indented blocks) are typeset
in a fixed-width font and may not fit into the width of the page. To
avoid this, the lines in the code examples should not be longer than
about 50 characters.

The current implementation uses a "report" style which allows chapters, sections, subsections and includes an automatically generated table of contents and an index.
The standard 10 point font and two-column format are used to save space (and trees).

The script {txt2yacasdoc.pl} attempts to convert double quotes {""}
into proper English quotation marks "".
However, this automatic conversion sometimes fails and produces wrongly-directed quotes.
One such case is if the quotes are on the same line as a TAB character (e.g. in an itemized environment).
This problem can be circumvented by putting the quoted words on a different line.

Some complicated mathematical expressions may not correctly render in $TeX$.
This is because Yacas uses its library 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 (preferably to itself) and not cause syntax
errors. In case of doubt, check that the expression evaluates without errors
and then try to use {TeXForm} on that expression and see if that evaluates
without errors as well. For example, expressions such as {x=+1} will cause a syntax error and this will break the compilation of the manual (both HTML and $TeX$).

	    {book2ys}: extracting Yacas code from books ("literate programming")

*A documentation!embedded code
*A documentation!literate programming
{book2ys.sh} is a shell script that extracts Yacas code examples from a documentation chapter into a separate file.
All other text is omitted.

Usage is similar to {book2TeX.sh}. For example, the benchmarking test code {wester.yts} can be automatically extracted from the corresponding essay chapter by the command
	sh ../manmake/book2ys.sh wester-1994.chapt \
	  wester.yts
After this command, the file {wester.yts} is created. Note that {wester-1994.chapt} is in Yacas language and is itself a generated file.

To prepare a documentation chapter in such a way that code extraction is possible, one needs to make sure that <i>all</i> code examples in the chapter taken together will become a correct sequence of Yacas expressions when cut out and written sequentially into a file.
So, for instance, semicolons at the end of each statement are required.
The script {book2ys} will <i>not</i> export example Yacas session code with "{In>}" and "{Out>}" prompts but it will export <i>all other</i> example code.

The example code with "{In>}" and "{Out>}" prompts will become comments in the exported Yacas file.
It is possible to suppress this comment generation by the {-strip} option to the {book2ys.sh} script.

If the output file name is not given, the name will be the same as the Yacas book source name but with the {.ys} extension.

See the source file {wester-1994.chapt.txt} to get a feeling of how the source documentation is formatted to allow completely automatic code extraction. Note that the printed documentation may be in twocolumn format, and therefore it is necessary to split lines that are too long.

Using the script {book2ys.sh}, one can write documentation and code together, a la "literate programming".
The main idea of literate programming is that the program code and the documentation should be written as one large book explaining to humans how the program is organized and how it works.
From this book, a printable copy is generated and all code is automatically extracted for compilation.

Literate programming may require that code be split between many source files, and yet it may be convenient to keep all descriptions in one book.
The special document formatting label {*YSFILE} can be used to redirect output to different Yacas source files.

By default, the output goes to the file specified on the {book2ys.sh} command line.
This default can be restored by the directive "{*YSFILE -}" at any time.
Otherwise, all code output will be printed to the file specified after the {*YSFILE} label.

Note that the multiple file support is somewhat restrictive:
*	Once the output file name has been changed, the old file is closed and cannot be appended to. (This is a limitation of the {ToFile()} function in Yacas.)
*	If the same file name is chosen again, the file will be overwritten.
*	If the output file has been changed at least once,
then at the end of the document the file name must be reset to the default "{-}".
Otherwise the last file will not be properly closed.

Here is an example of using multiple files. Note how documentation text is interspersed with TAB-indented code.

	Text that does not appear in the code.
	    // code into default file
	    // more code
	*YSFILE script1.ys
	This will not appear in the file.
	    x:=1;
	    // some code for the file script1.ys
	*YSFILE script2.ys
	    // some code for the file script2.ys
	End of the example, need to reset *YSFILE.
	*YSFILE -
After processing this file with {book2ys.sh}, one should get three files with Yacas code.

	    {ys2book}: extracting documentation from Yacas code ("literate programming")

*A documentation!embedded in code
*A documentation!literate programming
The standard view of literate programming is that one prepares a book readable by humans, and all code is automatically extracted from the book.
The focus in this approach is on writing explanations on how the code works.

The converse approach is to write primarily code and
embed some documentation as comments in the code files.
This approach is implemented by the script {ys2book.pl}.

This script takes a Yacas script file and extracts Yacas comments from it into another file.
Usage may look like this:

	perl ys2book.pl < file.ys > file.chapt.txt
	perl ys2book.pl -strip < file.ys > file.chapt.txt
Here {file.ys} is the source file and {file.chapt.txt} is the output file.

Not all comments may be desirable as documentation.
Formatting of comments is implemented as follows:

*	Line comments starting at the beginning of line with three or more slashes
("{///}", "{////}" etc.) are exported as documentation.
Line comments starting with "{//}" are not exported.
Line comments that are found after some Yacas statements are also not exported.
For example, if the source file contains the following lines,
	a:=1; // initialize a.
	   ///// This function needs
	  ///   an initializer.
	b:=1; /// also initialize b.
then only the text
	This function needs
	an initializer.
will appear in the output file.
Note that the initial spaces are stripped from the line comment strings.
*	Block comments starting with
"{/**}" become documentation.
The block comment must be the only content of the line.
For example,
	/** documentation text */
	/**   continues
	    here*/
will export the following:
	documentation text
	continues
	    here
Note that some initial spaces have been stripped.
See below for more detail about the stripping of spaces.
*	Multiline comments marked with an initial asterisk
"{*}" become documentation with the initial asterisk removed.
For example, in the block comment
	/** This starts
	 * a multiline
	 * comment.
	 */ 
the initial {*} and any spaces before it will be removed from each line.
This feature is designed to make the format easier to comprehend visually, if the documentation needs to be specially formatted.
*	All other comments remain unexported code comments.
*	All Yacas code, including unexported comments, is TAB-indented and printed to the output file, unless the "{-strip}" option is given.
(TAB-indentation is the Yacas documentation markup for code examples.)
With the "{-strip}" option, the output file will contain only exportable documentation comments and no code samples.

All exported text is printed to the output file as is, without any additional reformatting.
The only change to the text is stripping of initial spaces.

Any leading spaces after the beginning of the comment sign are removed.
For example,
	/*      text */
will be exported as just "text" without the leading spaces.
In a multiline comment, such as
	/*    start
	      of comment */
the leading spaces in the first line will be stripped.
However, the leading spaces (and TABs) in other lines of the multiline comment block will be preserved.

Empty lines can be introduced into the documentation either as part of a multiline comment block, or as a standalone empty comments such as
	///
	////////

With these features it is easy to prepare the embedded documentation in the Yacas plaintext documentation format.
This format requires space- and TAB-based formatting, which is mostly preserved by the script {ys2book.pl}.

	    {ytxt2tex}: Conversion of plain text documentation to $LaTeX$

*A documentation!outside of Yacas source tree
An auxiliary script {ytxt2tex} converts plain text documentation to $LaTeX$.
The script {ytxt2tex} can be used outside of the Yacas source tree to convert individual documents to $LaTeX$.
This is useful if you would like to produce $TeX$ documents and if you find the plain text format of the Yacas documentation more comfortable.
Therefore, {ytxt2tex} is a kind of a special-purpose $TeX$ preprocessor designed for producing Yacas documentation.

This is a standalone script; it is installed by default into {/usr/local/bin} and requires the Yacas executable also on the path, as well as the script files {book2TeX.*} and {txt2yacasdoc.pl} in the {/manmake} subdirectory of the Yacas installation tree {/usr/local/share/yacas/}.
The script also requires {perl} and the Unix shell {sh}.

Limitations of this script are:
*	it is impossible to include raw $TeX$ code;
*	mathematical expressions are limited to those representable using Yacas functions and operators from the standard library;
*	the document comes out to be a twocolumn "report" with a certain fixed title page format, a table of contents, and an index;
*	front matter is fixed
("<i>This is Yacas documentation... by the Yacas team... GNU Free Documentation License...</i>" etc.) and will most probably have to be edited by hand if you need to prepare anything other than Yacas documentation;
*	all current limitations of plaintext documentation format, for example, no nested itemized/enumerated environments;
*	some advanced features of index generation (e.g. the {!} separators combined with other markup) are not yet supported.

These limitations may be easily overcome by editing the resulting $TeX$ file (but you need to know at least some $TeX$ to do that).

The general usage pattern is
	ytxt2tex [-o outputfile] file1.txt [file2.txt] ...
All source files must have extension ".txt".
The command-line option {-o} specifies the name of the output $TeX$ file.
If the {-o} option is not given, the output file will be {file1.tex} (i.e. the name of the first {.txt} file with the {.tex} extension).
If several {.txt} files are given, the first one must {*INCLUDE} all others.

To illustrate the usage of the script {ytxt2tex}, consider two examples.

The first example is just one plaintext file {example1.txt}. This file will have to be a "book" in itself, i.e. it will have to include a book title indented by four TAB symbols. For example:

	*REM file: example1.txt
	                Example Document Title
	*REM this is a section title:
			Numbers and letters
	*REM here are some index entries:
	*A numbers
	*REM simple index entries like this are OK
	*A letters
	
	Numbers and letters are very important, etc.

This file {example1.txt} can be converted to a $LaTeX$ file {example1.tex} by the following simple command:
	ytxt2tex example1.txt
If the resulting file should be named something other than {example1.tex}, say {output1.tex}, then the command is
	ytxt2tex -o output1.tex example1.txt

The second example is a longer "book" consisting of several plaintext files.
One of these files is a "master file" and it should include all other files using the {*INCLUDE} label.
The {*INCLUDE} label should contain file names without the {.txt} extension.

Suppose we have prepared the files {book1.txt}, {chapter1.txt}, and {chapter2.txt} containing the preamble text and two chapters.
For example:

	*REM this is the file "book1.txt"
	*BLURB or, The Multitudinous Attempts
	to Avoid Counterproductivity
	                 Relationships of Entities
	*INCLUDE chapter1
	*INCLUDE chapter2

The chapter files might be:

	*REM this is the file "chapter1.txt"
	        Entities and Epiphenomena
	The history of the ambiguous question of
	epiphenomenological discourse can be
	traced to the pre-postmodern period...

	*REM this is the file "chapter2.txt"
	        Substrates and Superficiality
	In the preceding chapter, we have thoroughly
	investigated the metaphilosophical aspects of
	the trans-homocentric considerations...

The command to create the final $LaTeX$ file {book1.tex} is
	ytxt2tex book1.txt chapter1.txt chapter2.txt
The "master file" {book1.txt} that includes all other text files must be given first.
The {-o} option can be used if the final $LaTeX$ file should be named something else than {book1.tex}. For example,
	ytxt2tex -o MyBook.tex book1.txt chapter*.txt

By default, both table of contents and the index are generated.
The commands to create a PostScript file out of the $LaTeX$ file might be:
	latex MyBook.tex
	latex MyBook.tex
	makeindex MyBook.idx -o MyBook.ind
	latex MyBook.tex

Note that the resulting $LaTeX$ file needs to be processed three times if the table of contents or index are to be used.
Without a table of contents and index, it is enough to process the file with $LaTeX$ twice.

	    {book2txt}: Conversion of existing documentation to plain text

(Note: as of version 1.0.49, all Yacas documentation is converted to plaintext format. This section is left for reference only.)

Currently, most but not all of the Yacas documentation markup functionality is
implemented in the simple plaintext filter; also, documentation includes some
extra HTML files. However, almost all of the reasonable markup needed to write
documentation is present. Therefore it is possible to maintain most of the
documentation in the plain text format described above. To convert existing
Yacas documentation back to the plain text format, a script
{book2txt.ys}/{book2txt.sh} can be used.

By using a command such as
	book2txt.sh file.chapt
one can create a source text file {file.chapt.txt} corresponding to the Yacas documentation file {file.chapt}. For example:

	12:51pm scriabin> book2txt.sh intro.book
	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");
This requires that the Yacas script {book2txt.ys} be available in the current directory. The shell script {book2txt.sh} assumes that {book2txt.ys} is stored in the same directory as {book2txt.sh}.

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
Each file is processed by an independent Yacas session. Any errors of processing are printed on the screen.