texmacs
/
doc
mirror of https://github.com/texmacs/doc.git
1
0
Fork 0
Code

Update documentation on tmdoc style

This commit is contained in:
Joris van der Hoeven 2012-02-03 21:39:51 +00:00
parent c22f0c47f1
commit 7593e603b3
10 changed files with 322 additions and 170 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

82
about/contribute/documentation/copyright.en.tm
View File

@ -1,68 +1,58 @@
<TeXmacs|1.0.0.17>
<TeXmacs|1.0.7.14>
<style|tmdoc>
<\body>
<expand|tmdoc-title|Copyright information & the Free Documentation License>
<tmdoc-title|Specifying meta information for documentation files>
All documentation on the <verbatim|texmacs-doc> site falls under the
<apply|hyper-link|GNU Free Documentation License|../../../fdl.txt>. If you
write documentation for <TeXmacs> on this site, then you have to agree that
it will be distributed under this license too. The copyright notice
Appropriate meta data for <TeXmacs> documentation can be entered from the
<menu|Manual|Meta data> menu. In particular, you should specify a title for
each documentation file using <menu|Manual|Meta data|Title>, or by directly
clicking on the <menu|Title> button on the focus bar after creating a new
document with the <tmstyle|tmdoc> style.
<\expand|quote>
All <TeXmacs> documentation falls under the <hlink|GNU Free Documentation
License|../../../fdl.txt>. If you want your documentation to be included in
<TeXmacs>, then you have to agree that it will be distributed under this
license too. The license information
<\quote-env>
<verbatim|Permission is granted to copy, distribute and/or modify this
document under the terms of the GNU Free Documentation License, Version
1.1 or any later version published by the Free Software Foundation; with
no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
Texts. A copy of the license is included in the section entitled "GNU
Free Documentation License".>
</expand>
</quote-env>
should be specified at the end of <em|each> file. This should be done
inside the <markup|tmdoc-license> macro, in a similar way as at the end of
the present document. When automatically generating a printed book from
several documentation files, this will enable us to include the license
only once.
should be specified at the end of <em|each> file. This can be done by
clicking on <menu|Manual|Meta data|GNU FDL>.
You keep (part of) the copyright of all documentation that you will write
for <TeXmacs> on the official <verbatim|texmacs-doc> site. When you or
others make additions to (or modifications in, or translations of) the
document, then you should add your own name (at an appropriate place,
usually at the end) to the existing copyright information. The copyright
notice should be specified using the <markup|tmdoc-copyright> function just
before the license information at the end of the document. The first
argument of this function contains a year or a period. Each remaining
argument indicates one of the copyright holders. When combining (pieces of)
several documents into another one, you should merge the copyright holders.
For cover information (on a printed book for instance), you are allowed to
list only the principal authors, but a complete list should be given at a
clearly indicated place.
In a similar manner, you may add a copyright notice by clicking on
<menu|Manual|Meta data|Copyright>. You keep (part of) the copyright of any
documentation that you will write for <TeXmacs>. When you or others make
additions to (or modifications in, or translations of) the document, then
you should add your own name (at an appropriate place, usually at the end)
to the existing copyright information. The first argument of the
<markup|tmdoc-copyright> macro contains a year or a period of years. Each
remaining argument indicates one of the copyright holders. When combining
(pieces of) several documents into another one, you should merge the
copyright holders. For cover information (on a printed book for instance),
you are allowed to list only the principal authors, but a complete list
should be given at a clearly indicated place.
<apply|tmdoc-copyright|1998--2002|Joris van der Hoeven>
<tmdoc-copyright|1998--2002|Joris van der Hoeven>
<expand|tmdoc-license|Permission is granted to copy, distribute and/or
modify this document under the terms of the GNU Free Documentation License,
Version 1.1 or any later version published by the Free Software Foundation;
with no Invariant Sections, with no Front-Cover Texts, and with no
Back-Cover Texts. A copy of the license is included in the section entitled
"GNU Free Documentation License".>
<tmdoc-license|Permission is granted to copy, distribute and/or modify this
document under the terms of the GNU Free Documentation License, Version 1.1
or any later version published by the Free Software Foundation; with no
Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
Texts. A copy of the license is included in the section entitled "GNU Free
Documentation License".>
</body>
<\initial>
<\collection>
<associate|paragraph width|150mm>
<associate|odd page margin|30mm>
<associate|shrinking factor|4>
<associate|page right margin|30mm>
<associate|page top margin|30mm>
<associate|reduction page right margin|25mm>
<associate|page type|a4>
<associate|reduction page bottom margin|15mm>
<associate|even page margin|30mm>
<associate|reduction page left margin|25mm>
<associate|page bottom margin|30mm>
<associate|reduction page top margin|15mm>
<associate|language|english>
</collection>
</initial>
</initial>

12
about/contribute/documentation/cvs.en.tm
View File

@ -1,4 +1,4 @@
<TeXmacs|1.0.7.12>
<TeXmacs|1.0.7.14>
<style|tmdoc>
@ -11,11 +11,11 @@
<verbatim| \ \ \ <hlink|http://www.texmacs.org/tmweb/download/svn.en.html|http://www.texmacs.org/tmweb/download/svn.en.html>>
In fact, the <name|cvs> system is not ideal for our documentation purpose,
because it is not very dynamic. In the future, we plan to create a
dedicated publication website, which will allow you to save documents
directly to the web. It should also allow the automatic conversion of the
documentation to other formats, the compilation of books, etc.
In fact, SVN is not ideal for our documentation purpose, because it is not
very dynamic. In the future, we plan to create a dedicated publication
website, which will allow you to save documents directly to the web. It
should also allow the automatic conversion of the documentation to other
formats, the compilation of books, etc.
<tmdoc-copyright|1998--2002|Joris van der Hoeven>

5
about/contribute/documentation/documentation.en.tm
View File

@ -1,4 +1,4 @@
<TeXmacs|1.0.7.12>
<TeXmacs|1.0.7.14>
<style|tmdoc>
@ -18,7 +18,8 @@
<branch|Directories and file names|file-names.en.tm>
<branch|Copyright information and the license|copyright.en.tm>
<branch|Specifying meta information for documentation
files|copyright.en.tm>
<branch|Automatic traversal of the documentation|traversal.en.tm>

7
about/contribute/documentation/introduction.en.tm
View File

@ -1,4 +1,4 @@
<TeXmacs|1.0.7.12>
<TeXmacs|1.0.7.14>
<style|tmdoc>
@ -23,6 +23,11 @@
well as indications on how to <hlink|traverse|traversal.en.tm> your
documentation, if it contains <hlink|many files|file-names.en.tm>.
When selecting the <tmstyle|tmdoc> document style, the top level
<menu|Manual> menu will appear automatically, together with some additional
icons. The most important tags for documentation purposes can be found in
this menu.
<\warning>
Don't forget to select <menu|Document|Language|Your language> for each
translated file. This will cause some content to be translated

49
about/contribute/documentation/tmdoc-annotate.en.tm Normal file
View File

@ -0,0 +1,49 @@
<TeXmacs|1.0.7.14>
<style|tmdoc>
<\body>
<tmdoc-title|Common annotations>
The <menu|Manual|Annotate> and <icon|tm_tmdoc_annotate.xpm> menus contain
the following useful macros for common annotations. You should use them
whenever appropriate.
<\description>
<item*|<markup|markup>>This macro is used in order to indicate a macro or
a function like <markup|section>.
<item*|<markup|src-arg>>This macro should be used in order to indicate
macro arguments such as <src-arg|body>.
<item*|<markup|src-var>>This macro is used for the indication of
environment variables such as <src-var|font-size>.
<item*|<markup|src-length>>This macro is used in order to indicate a
length such as <src-length|12em>.
<item*|<markup|tmstyle>>This macro indicates the name of a <TeXmacs>
style file or package like <tmstyle|article>.
<item*|<markup|tmpackage>>This macro indicates the name of a <TeXmacs>
package like <tmpackage|std-markup>.
<item*|<markup|tmdtd>>This macro indicates the name of a <TeXmacs>
<abbr|d.t.d.> like <tmdtd|number-env>.
</description>
<tmdoc-copyright|1998--2011|Joris van der Hoeven>
<tmdoc-license|Permission is granted to copy, distribute and/or modify this
document under the terms of the GNU Free Documentation License, Version 1.1
or any later version published by the Free Software Foundation; with no
Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
Texts. A copy of the license is included in the section entitled "GNU Free
Documentation License".>
</body>
<\initial>
<\collection>
<associate|language|english>
</collection>
</initial>

60
about/contribute/documentation/tmdoc-explain.en.tm Normal file
View File

@ -0,0 +1,60 @@
<TeXmacs|1.0.7.14>
<style|tmdoc>
<\body>
<tmdoc-title|Explanations of macros, environment variables, and so on>
The main environment which is used for explanations of macros, environment
variables, <scheme> functions, <abbr|etc.> is inserted using the
<subsubmenu|Manual|Explain|Explanatory item> entry of the
<menu|Manual|Explain> and <icon|tm_explain.xpm> menus. The environment
comes with two arguments: the first argument consists of the concept or
concepts to be explained, and the second one contains the actual
explanation. A typical example would be the following:
<\explain>
<explain-macro|demo-tag|body>
<explain-macro|demo-tag|extras|body><explain-synopsis|short and long
versions of a demo tag>
<|explain>
The <markup|demo-tag> is used for demonstration purposes and decorates
the <src-arg|body><compound|src-var|> argument. An optional argument
<src-arg|extras> can be given with details on the way to decorate the
<src-arg|body>.
</explain>
In this example, we used <menu|Manual|Explain|TeXmacs macros> twice in
order to insert the macros to be described. We also used
<menu|Manual|Explain|Synopsis> in order to give a short description of the
tags (in grey). In a similar way, one may use
<menu|Manual|Explain|Environment variable> in order to describe an
environment variable. Another example is:
<\explain>
<scm|(foo-bar <scm-arg|K> <scm-arg|x>)>
<|explain>
The function <scm|foo-bar> computes the foo-bar transform of the operator
<scm|<scm-arg|K>> and applies it to <scm|<scm-arg|x>>.
</explain>
In this example, we notice that all <scheme> code was encapsulated into
<markup|scm> tags (see <menu|Insert|Program|Inline code|Scheme>) and
arguments were tagged using <markup|scm-arg>.
<tmdoc-copyright|1998--2011|Joris van der Hoeven>
<tmdoc-license|Permission is granted to copy, distribute and/or modify this
document under the terms of the GNU Free Documentation License, Version 1.1
or any later version published by the Free Software Foundation; with no
Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
Texts. A copy of the license is included in the section entitled "GNU Free
Documentation License".>
</body>
<\initial>
<\collection>
<associate|language|english>
</collection>
</initial>

69
about/contribute/documentation/tmdoc-gui.en.tm Normal file
View File

@ -0,0 +1,69 @@
<TeXmacs|1.0.7.14>
<style|tmdoc>
<\body>
<tmdoc-title|Graphical user interface related markup>
The following markup elements can be used in order to describe various
graphical user interface elements, such as keyboard shortcuts, menus or
icons.
<\description>
<item*|<markup|shortcut>>This macro is used to indicate a keyboard
shortcut for a <scheme> command. For instance, the shortcut for
<scm|(new-buffer)> is <shortcut|(new-buffer)>.
<item*|<markup|key>>This unary macro is used for explicit keyboard input.
For instance, when giving <rigid|<verbatim|A C-b return>> as argument,
the result is <key|A C-b return>.
<item*|<markup|menu>>This function with an arbitrary number of arguments
indicates a menu like <menu|File> or <menu|Document|Language>. Menu
entries are automatically translated by this function.
<item*|<markup|submenu>>Consider the following sentence:
<\quote-env>
``You may use the <submenu|File|Load> and <submenu|File|Save> entries
of the <menu|File> menu in order to load and save files.''
</quote-env>
In this example, the menu entries <submenu|File|Load> and
<submenu|File|Save> were marked using the <markup|submenu> tag, which
takes the implicit <menu|File> menu as its first invisible argument. This
invisible argument is still taken into account when building the index
(for instance). In a similar way, we provide <markup|subsubmenu> and
<markup|subsubsubmenu> tags.
<item*|<markup|icon>>Can be used in order to specify one of the <TeXmacs>
icons, such as <icon|tm_open.xpm> and <icon|tm_save.xpm>. The macro takes
one argument with the file name of the icon (the full path is not
needed).
<item*|<markup|screenshot>>Similar to the <markup|icon> tag, but for
screenshots.
</description>
Notice that the contents of none of the above tags should be translated
into foreign languages. Indeed, for menu tags, the translations are done
automatically, so as to keep the translations synchronized with the
translations of the actual <TeXmacs> menus. In the cases of markup, styles,
packages and <abbr|d.t.d.>s, it is important to keep the original name,
because it often corresponds to a file name.
<tmdoc-copyright|1998--2011|Joris van der Hoeven>
<tmdoc-license|Permission is granted to copy, distribute and/or modify this
document under the terms of the GNU Free Documentation License, Version 1.1
or any later version published by the Free Software Foundation; with no
Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
Texts. A copy of the license is included in the section entitled "GNU Free
Documentation License".>
</body>
<\initial>
<\collection>
<associate|language|english>
</collection>
</initial>

53
about/contribute/documentation/tmdoc-misc.en.tm Normal file
View File

@ -0,0 +1,53 @@
<TeXmacs|1.0.7.14>
<style|tmdoc>
<\body>
<tmdoc-title|Miscellaneous markup>
Some other potentially useful macros are the following:
<\description>
<item*|<markup|tm-fragment>>For indicating some <TeXmacs> document
fragment. This macro is especially useful for <TeXmacs> source code, as
in
<\tm-fragment>
<inactive*|<assign|red-text|<macro|body|<with|color|red|<arg|body>>>>>
</tm-fragment>
In this example, we used the keyboard shortcut <shortcut|(make-mod-active
'inactive*)> in order to disactivate the source code inside an active
outer document.
<item*|<markup|descriptive-table>>For descriptive tables; such tables can
be used to document lists of keyboard shortcuts, different types of
markup, <abbr|etc.>
<item*|<markup|cursor>>This macro can be used to indicate a cursor
position, as in <math|a<rsup|2>+b<rsup|2<cursor>>=c<rsup|2>>.
<item*|<markup|small-focus>, <markup|small-envbox>>This macro can be used
for indicating the visual aids around the current focus and the further
outer context (<abbr|e.g.> <math|<small-envbox|a+<frac|b|<small-focus|c>>>>),
in the case of inline elements.
<item*|<markup|big-focus>, <markup|big-envbox>>Block versions of
<markup|small-focus> and <markup|small-envbox>.
</description>
<tmdoc-copyright|1998--2011|Joris van der Hoeven>
<tmdoc-license|Permission is granted to copy, distribute and/or modify this
document under the terms of the GNU Free Documentation License, Version 1.1
or any later version published by the Free Software Foundation; with no
Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
Texts. A copy of the license is included in the section entitled "GNU Free
Documentation License".>
</body>
<\initial>
<\collection>
<associate|language|english>
</collection>
</initial>

97
about/contribute/documentation/tmdoc-style.en.tm
View File

@ -1,4 +1,4 @@
<TeXmacs|1.0.7.12>
<TeXmacs|1.0.7.14>
<style|tmdoc>
@ -8,92 +8,25 @@
Besides the <hlink|copyright information|copyright.en.tm> macros and
<hlink|traversal macros|traversal.en.tm>, which have been documented
before, the <tmstyle|tmdoc> style comes with a certain number of other
macros and functions, which you should use whenever appropriate:
macros and functions, which you should use whenever appropriate.
<\description>
<item*|<markup|shortcut>>This macro is used to indicate a keyboard
shortcut for a <scheme> command. For instance, the shortcut for
<scm|(new-buffer)> is <shortcut|(new-buffer)>.
Notice that the <tmstyle|tmdoc> style inherits from the <tmstyle|generic>
style, so you should use macros like <markup|em>, <markup|verbatim>,
<markup|itemize>, <abbr|etc.> from this style whenever appropriate. In
particular, when documentating program code, you should use
<menu|Insert|Program|Inline code> and <menu|Insert|Program|Block of code>
in order to mark such pieces of code.
<item*|<markup|key>>This unary macro is used for explicit keyboard input.
For instance, when giving <rigid|<verbatim|A C-b return>> as argument,
the result is <key|A C-b return>.
<\traverse>
<branch|Explanations of macros, environment variables, and so
on|tmdoc-explain.en.tm>
<item*|<markup|menu>>This function with an arbitrary number of arguments
indicates a menu like <menu|File> or <menu|Document|Language>. Menu
entries are automatically translated by this function.
<branch|Graphical user interface related markup|tmdoc-gui.en.tm>
<item*|<markup|markup>>This macro is used in order to indicate a macro or
a function like <markup|section>.
<branch|Common annotations|tmdoc-annotate.en.tm>
<item*|<markup|tmstyle>>This macro indicates the name of a <TeXmacs>
style file or package like <tmstyle|article>.
<item*|<markup|tmpackage>>This macro indicates the name of a <TeXmacs>
package like <tmpackage|std-markup>.
<item*|<markup|tmdtd>>This macro indicates the name of a <TeXmacs>
<abbr|d.t.d.> like <tmdtd|number-env>.
</description>
Notice that the contents of none of the above tags should be translated
into foreign languages. Indeed, for menu tags, the translations are done
automatically, so as to keep the translations synchronized with the
translations of the actual <TeXmacs> menus. In the cases of markup, styles,
packages and <abbr|d.t.d.>s, it is important to keep the original name,
because it often corresponds to a file name.
The following macros and functions are used for linking and indexing
purposes, although they should be improved in the future:
<\description>
<item*|<markup|simple-link>>This macro takes an URL <math|x> as argument
and is a hyperlink with name and destination <math|x>.
<item*|<markup|hyper-link>>This macro is a usual hyperlink.
<item*|<markup|concept-link>>This macro takes a concept as argument.
Later on an appropriate hyperlink might be created automatically from
this and the other documentation.
<item*|<markup|only-index>>Index a simple string.
<item*|<markup|def-index>>Definition of a new concept; the text is
printed in italic and indexed.
<item*|<markup|re-index>>Reappearance of an already defined concept; the
text is printed in roman and put in the index.
</description>
The following tags are also frequently used:
<\description>
<item*|<markup|scheme>>The <scheme> language.
<item*|<markup|c++>>The <c++> language.
<item*|<markup|framed-fragment>>For displaying a piece of code in a nice
frame.
<item*|<markup|tm-fragment>>Single out a fragment of a <TeXmacs>
document.
<item*|<markup|scm-code>>For multi-paragraph <scheme> code.
<item*|<markup|cpp-code>>For multi-paragraph <c++> code.
<item*|<markup|scm>>For a short piece of <scheme> code.
<item*|<markup|cpp>>For a short piece of <c++> code.
<item*|<markup|descriptive-table>>For descriptive tables; such tables can
be used to document lists of keyboard shortcuts, different types of
markup, <abbr|etc.>
</description>
The <tmstyle|tmdoc> style inherits from the <tmstyle|generic> style and you
should use macros like <markup|em>, <markup|verbatim>, <markup|itemize>,
<abbr|etc.> from this style whenever appropriate.
<branch|Miscellaneous markup|tmdoc-misc.en.tm>
</traverse>
<tmdoc-copyright|1998--2011|Joris van der Hoeven>

58
about/contribute/documentation/traversal.en.tm
View File

@ -1,9 +1,9 @@
<TeXmacs|1.0.0.17>
<TeXmacs|1.0.7.14>
<style|tmdoc>
<\body>
<expand|tmdoc-title|Traversing the <TeXmacs> documentation>
<tmdoc-title|Traversing the <TeXmacs> documentation>
As a general rule, you should avoid the use of sectioning commands inside
the <TeXmacs> documentation and try to write small help pages on well
@ -14,46 +14,38 @@
The <tmstyle|tmdoc> style provides three markup macros for indicating how
to traverse documentation. The <markup|traverse> macro is used to
encapsulate regions with traversal information. The <markup|branch> macro
indicates a help page which should be considered as a subsection and the
<markup|continue> macro indicates a follow-up page. Both the
<markup|branch> and the <markup|continue> macro take two arguments. The
first argument describes the link and the second argument gives the
physical relative address of the linked file.
encapsulate regions with traversal information. It can be inserted using
the <subsubmenu|Manual|Traversal|Traverse> entry in the
<menu|Manual|Traversal> or <icon|tm_traverse.xpm> menu. The <markup|branch>
and <markup|extra-branch> macros indicate help pages which should be
considered as a subsection and an appendix respectively, whereas the
<markup|continue> macro indicates a follow-up page. Each of these macros
should be used inside a <markup|traverse> environment and each of these
macros takes two arguments. The first argument describes the link and the
second argument gives the physical relative address of the linked file.
Typically, at the end of a meta help file you will find several
<markup|branch> or <markup|continue> macros, inside one <markup|traverse>
macro. At the top of the document, you should also specify a title for your
document using the <markup|tmdoc-title> macro. When generating a printed
manual from the documentation, a chapter-section-subsection structure will
automatically be generated from this information and the document titles.
Alternatively, one might automatically generate additional buttons for
navigating inside the documentation using a browser.
document using the <markup|tmdoc-title> macro, as <hlink|described
before|copyright.en.tm>. When generating a printed manual from the
documentation, a chapter-section-subsection structure will automatically be
generated from this information and the document titles. Alternatively, one
might automatically generate additional buttons for navigating inside the
documentation using a browser.
<apply|tmdoc-copyright|1998--2002|Joris van der Hoeven>
<tmdoc-copyright|1998--2002|Joris van der Hoeven>
<expand|tmdoc-license|Permission is granted to copy, distribute and/or
modify this document under the terms of the GNU Free Documentation License,
Version 1.1 or any later version published by the Free Software Foundation;
with no Invariant Sections, with no Front-Cover Texts, and with no
Back-Cover Texts. A copy of the license is included in the section entitled
"GNU Free Documentation License".>
<tmdoc-license|Permission is granted to copy, distribute and/or modify this
document under the terms of the GNU Free Documentation License, Version 1.1
or any later version published by the Free Software Foundation; with no
Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
Texts. A copy of the license is included in the section entitled "GNU Free
Documentation License".>
</body>
<\initial>
<\collection>
<associate|paragraph width|150mm>
<associate|odd page margin|30mm>
<associate|shrinking factor|4>
<associate|page right margin|30mm>
<associate|page top margin|30mm>
<associate|reduction page right margin|25mm>
<associate|page type|a4>
<associate|reduction page bottom margin|15mm>
<associate|even page margin|30mm>
<associate|reduction page left margin|25mm>
<associate|page bottom margin|30mm>
<associate|reduction page top margin|15mm>
<associate|language|english>
</collection>
</initial>
</initial>