README
1%------------------------------------------------------------
2== HOW TO WRITE AN ENTRY IN CoCoAHelp.Xml ==
3%------------------------------------------------------------
4
5=== Command ===
6
7place the command in alphabetical order with this structure
8```
9<command>
10 <title>xxx</title>
11 <short_description>xxx</short_description>
12
13<syntax>
14xxx(L:LIST): LIST
15xxx(L:LIST, N:INT): LIST
16</syntax>
17<description>
18xxx yyy zzz...
19
20<example>
21/**/ INPUT
22OUTPUT
23
24/**/ INPUT
25OUTPUT
26</example>
27</description>
28
29<types>
30 <type>xxx</type>
31</types>
32
33<keys>
34 <key>xxx</key>
35</keys>
36
37<seealso>
38 <see>xxx</see>
39</seealso>
40</command>
41```
42
43When called the first time CoCoA-5 reads the whole file and stores the fields
44in title, keys, syntax.
45The search for the required entry is done using this table (in C++).
46
47Then rereads the file to get and print the entry:
48so, if you make a change in CoCoAHelp.xml in the description or example
49it will work without reloading the manual,
50and if you make a change in CoCoAHelp.xml in the title (new entry) or in
51syntax, or search keys, you will need to call ``ReloadMan();`` for it to
52work.
53
54- order is not important (well, not much) but consistency help maintanance
55- the title is automatically a search "key" (so, no need to list it)
56- put no extra spaces in syntax and example because they are verbatim
57-
58
59== Tags ==
60
61//What font should one use when referring to params in the description?//
62Morally ``<tt>...</tt>``, but that's rarely done
63
64//How to make links to another entry?//
65``<ttref>entry</ttref>`` for commands and
66``<ref>title</ref>`` for other sections
67 (case sensitive)
68
69
70==== FULL EXAMPLE ====
71```
72<command>
73 <title>IsElem</title>
74 <short_description>checks if A is an element of B</short_description>
75
76<syntax>
77IsElem(A:RINGELEM, B:IDEAL): BOOL
78IsElem(A:MODULEELEM, B:MODULE): BOOL
79</syntax>
80
81<description>
82This function tests whether A is an element of B.
83Same as the command <ttref>IsIn</ttref>, but works on fewer types: it
84is in CoCoA-5 for compatibility with the C++ function in CoCoALib.
85
86<example>
87/**/ Use QQ[x,y,z];
88/**/ IsElem(x, Ideal(x+y, x-y));
89true
90
91/**/ x IsIn Ideal(x+y, x-y);
92true
93</example>
94</description>
95
96<types>
97 <type>ideal</type>
98 <type>module</type>
99 <type>boolean</type>
100</types>
101
102<seealso>
103 <see>IsIn</see>
104</seealso>
105
106</command>
107```