source: specdomain/src/specdomain/doc/spec.rst @ 937

Last change on this file since 937 was 937, checked in by jemian, 10 years ago

refs #8, document the commands, as they exist now

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision URL Header
File size: 5.4 KB
Line 
1.. $Id: spec.rst 937 2012-06-15 23:06:40Z jemian $
2
3Documenting SPEC Code
4========================
5
6.. _spec-directives:
7
8Describing SPEC objects
9-----------------------------------
10
11The following *directives* refer to objects in SPEC macro source code files
12and create index entries and identifiers:
13
14.. rst:directive::  spec:def
15
16   Declare the name of a SPEC ``def`` macro.
17   
18   +---------------------------+--------------------------+
19   | ReST code                 | Displays like            |
20   +===========================+==========================+
21   | ::                        | .. spec:def:: demo_def   |
22   |                           |                          |
23   |   .. spec:def:: demo_def  |                          |
24   +---------------------------+--------------------------+
25
26.. rst:directive::  spec:rdef
27
28   Declare the name of a SPEC ``rdef`` run-time-defined macro.
29   
30   +-----------------------------+----------------------------+
31   | ReST code                   | Displays like              |
32   +=============================+============================+
33   | ::                          | .. spec:rdef:: demo_rdef   |
34   |                             |                            |
35   |   .. spec:rdef:: demo_rdef  |                            |
36   +-----------------------------+----------------------------+
37
38.. rst:directive::  spec:cdef
39
40   Declare the name of a SPEC ``cdef`` chained macro.
41   
42   +-------------------------------------+------------------------------------+
43   | ReST code                           | Displays like                      |
44   +=====================================+====================================+
45   | ::                                  | .. spec:cdef:: cdef("demo_cdef")   |
46   |                                     |                                    |
47   |   .. spec:cdef:: cdef("demo_cdef")  |                                    |
48   +-------------------------------------+------------------------------------+
49
50   More elaborate example showing how to call a
51   chained macro and also describe the arguments::
52   
53                .. spec:cdef:: cdef("demo_cdef_more", "spec_code", "key", flags)
54                   
55                   :param str demo_cdef_more: name of chained macro
56                   :param str spec_code: SPEC code to be executed (usually a single macro name)
57                   :param str key: name of this part of the chained macro
58                   :param flags: see http://www.certif.com/spec_help/funcs.html
59                   :rtype: none
60                   
61                   This text is ignored (for now).
62   
63   Displays like:
64   
65   .. spec:cdef:: cdef("demo_cdef_more", "spec_code", "key", flags)
66
67           :param str demo_cdef_more: name of chained macro
68           :param str spec_code: SPEC code to be executed (usually a single macro name)
69           :param str key: name of this part of the chained macro
70           :param flags: see **SPEC** documentation for details
71           :rtype: none
72
73.. rst:directive::  spec:global
74
75   Declare the name of a SPEC global variable.
76   
77   +---------------------------------+--------------------------------+
78   | ReST code                       | Displays like                  |
79   +=================================+================================+
80   | ::                              | .. spec:global:: demo_global   |
81   |                                 |                                |
82   |   .. spec:global:: demo_global  |                                |
83   +---------------------------------+--------------------------------+
84
85.. rst:directive::  spec:local
86
87   Declare the name of a SPEC local variable.
88   
89   +--------------------------------+-------------------------------+
90   | ReST code                      | Displays like                 |
91   +================================+===============================+
92   | ::                             | .. spec:local:: demo_local    |
93   |                                |                               |
94   |   .. spec:local:: demo_local   |                               |
95   +--------------------------------+-------------------------------+
96
97
98.. _spec-roles:
99
100Cross-referencing SPEC objects
101-----------------------------------
102
103The following *roles* refer to objects in SPEC macro source code files
104and are possibly hyperlinked if a matching identifier is found:
105
106.. rst:role:: spec:def
107
108   Reference a SPEC macro definition by name. 
109   (Do not include the argument list.)
110   
111   ::
112   
113                An example ``def`` macro: :spec:def:`demo_def`
114               
115   An example ``def`` macro: :spec:def:`demo_def`
116
117.. rst:role:: spec:rdef
118
119   Reference a SPEC run-time macro definition by name. 
120   (Do not include the argument list.)
121   
122   ::
123   
124                An example ``rdef`` macro: :spec:rdef:`demo_rdef`
125
126   An example ``rdef`` macro: :spec:rdef:`demo_rdef`
127
128.. rst:role:: spec:cdef
129
130   Reference a SPEC chained macro definition by name. 
131   (Do not include the argument list.)
132   
133   ::
134   
135                An example ``cdef`` macro: :spec:cdef:`cdef("demo_cdef")`
136                An example ``cdef`` macro: :spec:cdef:`cdef("demo_cdef_more")`.
137
138   An example ``cdef`` macro: :spec:cdef:`cdef("demo_cdef")`.
139   An example ``cdef`` macro: :spec:cdef:`cdef("demo_cdef_more")`.
140
141.. rst:role:: spec:global
142
143   Reference a global-scope variable.
144   
145   ::
146   
147                An example ``global`` variable: :spec:global:`demo_global`
148
149   An example ``global`` variable: :spec:global:`demo_global`
150   
151.. rst:role:: spec:local
152
153   Reference a local-scope variable.
154   
155   ::
156   
157                An example ``local`` variable: :spec:local:`demo_local`
158
159   An example ``local`` variable: :spec:local:`demo_local`
Note: See TracBrowser for help on using the repository browser.