| 1 | @ifclear singularmanual |
|---|
| 2 | This is the README file for lib2doc. |
|---|
| 3 | @end ifclear |
|---|
| 4 | |
|---|
| 5 | @code{lib2doc} is a utility to generate the stand-alone documentation for |
|---|
| 6 | a @sc{Singular} library in various formats. |
|---|
| 7 | |
|---|
| 8 | The @code{lib2doc} utility should be used by developers of @sc{Singular} |
|---|
| 9 | libraries to check the generation of the documentation of their |
|---|
| 10 | libraries. |
|---|
| 11 | |
|---|
| 12 | @code{lib2doc} can be downloaded from @* |
|---|
| 13 | @url{ftp://jim.mathematik.uni-kl.de/pub/Math/Singular/misc/lib2doc.tar.gz} |
|---|
| 14 | (mirror at @url{https://www.mathematik.uni-kl.de/ftp/pub/Math/Singular/misc/lib2doc.tar.gz}) |
|---|
| 15 | |
|---|
| 16 | |
|---|
| 17 | @strong{Important:} |
|---|
| 18 | @*To use @code{lib2doc}, you need |
|---|
| 19 | to have @code{perl} (version 5 or |
|---|
| 20 | higher), @code{texinfo} (version 3.12 or higher) and @code{Singular} |
|---|
| 21 | and @code{libparse} (version 1-3-4 or higher) installed on your system. |
|---|
| 22 | |
|---|
| 23 | To generate the documentation for a library, follow these steps: |
|---|
| 24 | @enumerate |
|---|
| 25 | @item |
|---|
| 26 | Unpack lib2doc.tar.gz |
|---|
| 27 | @smallexample |
|---|
| 28 | gzip -dc lib2doc.tar.gz | tar -pxf - |
|---|
| 29 | @end smallexample |
|---|
| 30 | and |
|---|
| 31 | @smallexample |
|---|
| 32 | cd lib2doc |
|---|
| 33 | @end smallexample |
|---|
| 34 | |
|---|
| 35 | @item |
|---|
| 36 | Edit the beginning of the file @code{Makefile}, filling in the values for |
|---|
| 37 | @code{SINGULAR} and @code{LIBPARSE}. Check also the values of @code{PERL} |
|---|
| 38 | and @code{LATEX2HTML}. |
|---|
| 39 | |
|---|
| 40 | @item |
|---|
| 41 | Copy your library to the current directory: |
|---|
| 42 | @smallexample |
|---|
| 43 | cp <path-where-your-lib-is>/mylib.lib . |
|---|
| 44 | @end smallexample |
|---|
| 45 | |
|---|
| 46 | @item |
|---|
| 47 | Now you can run the following commands: |
|---|
| 48 | @table @code |
|---|
| 49 | @item make mylib.hlp |
|---|
| 50 | Generates the file @code{mylib.hlp} -- the info file for the documentation |
|---|
| 51 | of @code{mylib.lib}. This file can be viewed using |
|---|
| 52 | @smallexample |
|---|
| 53 | info -f mylib.hlp |
|---|
| 54 | @end smallexample |
|---|
| 55 | @item make mylib.dvi |
|---|
| 56 | Generates the file @code{mylib.dvi} -- the dvi file for the documentation |
|---|
| 57 | of @code{mylib.lib}. This file can be viewed using |
|---|
| 58 | @smallexample |
|---|
| 59 | xdvi mylib.dvi |
|---|
| 60 | @end smallexample |
|---|
| 61 | @item make mylib.ps |
|---|
| 62 | Generates the file @code{mylib.ps} -- the PostScript file for the documentation |
|---|
| 63 | of @code{mylib.lib}. This file can be viewed using (for example) |
|---|
| 64 | @smallexample |
|---|
| 65 | ghostview mylib.dvi |
|---|
| 66 | @end smallexample |
|---|
| 67 | @item make mylib.html |
|---|
| 68 | Generates the file @code{mylib.html} -- the HTML file for the documentation |
|---|
| 69 | of @code{mylib.lib}. This file can be viewed using (for example) |
|---|
| 70 | @smallexample |
|---|
| 71 | firefox mylib.html |
|---|
| 72 | @end smallexample |
|---|
| 73 | @item make clean |
|---|
| 74 | Deletes all generated files. |
|---|
| 75 | @end table |
|---|
| 76 | |
|---|
| 77 | |
|---|
| 78 | Note that you can safely ignore messages complaining about undefined |
|---|
| 79 | references. |
|---|
| 80 | |
|---|
| 81 | @end enumerate |
|---|
| 82 | |
|---|
