1 | <!-- |
---|
2 | //----------------------------------------------------------- |
---|
3 | // Copyright Christian Arnault LAL-Orsay CNRS |
---|
4 | // arnault@lal.in2p3.fr |
---|
5 | // See the complete license in cmt_license.txt "http://www.cecill.info". |
---|
6 | //----------------------------------------------------------- |
---|
7 | --> |
---|
8 | |
---|
9 | <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN"> |
---|
10 | <html> |
---|
11 | <head> |
---|
12 | <title>FAQ on CMT</title> |
---|
13 | </head> |
---|
14 | |
---|
15 | <body> |
---|
16 | <center><h1>FAQ on CMT</h1></center> |
---|
17 | <h1>Index</h1> |
---|
18 | |
---|
19 | <ol> |
---|
20 | <li><a href="#Providing sourceless documents">Providing sourceless documents</a> |
---|
21 | <li><a href="#Accessing packages in a sub-directory">Accessing packages in a sub-directory</a> |
---|
22 | </ol> |
---|
23 | |
---|
24 | <hr> |
---|
25 | <h1><a name="Providing sourceless documents"/>Providing sourceless documents</h1> |
---|
26 | |
---|
27 | <blockquote> |
---|
28 | <i> |
---|
29 | I'm always trying to use CMT together with java and I now have |
---|
30 | problems with the documentation. |
---|
31 | |
---|
32 | <p> What I'd like to do is just generating automatically my |
---|
33 | documentation using javadoc. Since it is not done in cmt, I tried to |
---|
34 | write a new fragment to define a new document type : javadoc. |
---|
35 | |
---|
36 | <p>The problem is that the process of generating the doc is not a |
---|
37 | file to file process : it does not take a .java file to write a |
---|
38 | .html. It takes a java package name (which has no associated file) |
---|
39 | and returns many files. This is not possible with the current |
---|
40 | implementation of document. It seems that adding this feature would |
---|
41 | lead to write some code into cmt_generator. |
---|
42 | |
---|
43 | <p>Does anyone see another method to generate my documentation ? |
---|
44 | |
---|
45 | <p>Sebastien |
---|
46 | </i> |
---|
47 | </blockquote> |
---|
48 | |
---|
49 | <p>In fact what you ask for is already available in CMT, it is |
---|
50 | documented (although likely crypticly ;-) ) as follows : |
---|
51 | |
---|
52 | <p>Since your "document generator" does not make use of any source |
---|
53 | file per se, it's likely that you will provide as the fragments the |
---|
54 | following files (I use as an example the name "javadoc" for your |
---|
55 | document type): |
---|
56 | |
---|
57 | <font face="courier new, courier" COLOR="#770077"> |
---|
58 | <b> |
---|
59 | <pre> |
---|
60 | ... |
---|
61 | make_fragment javadoc_header |
---|
62 | make_fragment javadoc -header=javadoc_header |
---|
63 | ... |
---|
64 | </pre> |
---|
65 | </b> |
---|
66 | </font> |
---|
67 | |
---|
68 | <p> where javadoc is simply ... empty. |
---|
69 | |
---|
70 | <p>I remind you that here : |
---|
71 | |
---|
72 | <ul> |
---|
73 | <li> javadoc_header will be instanciated once per document |
---|
74 | <li> javadoc will be instanciated once per source file (thus never if |
---|
75 | no source file is specified) |
---|
76 | </ul> |
---|
77 | |
---|
78 | <p>Then a document associated with the javadoc type could be specified |
---|
79 | as follows, using the <i>unusual</i> feature I mentioned above |
---|
80 | |
---|
81 | <font face="courier new, courier" COLOR="#770077"> |
---|
82 | <b> |
---|
83 | <pre> |
---|
84 | document javadoc MyDoc JAVAPACKAGE=MyPackage |
---|
85 | </pre> |
---|
86 | </b> |
---|
87 | </font> |
---|
88 | |
---|
89 | <p>Here the syntax <b>JAVAPACKAGE=MyPackage</b> corresponds to |
---|
90 | providing user-defined templates in the document's fragments |
---|
91 | |
---|
92 | (see the general <a href="CMTDoc.html#kw-constituent-option">syntax</a>) |
---|
93 | |
---|
94 | every variable name should then correspond within the fragment to |
---|
95 | constructs like (appearing anywhere in the fragment) |
---|
96 | |
---|
97 | <font face="courier new, courier" COLOR="#770077"> |
---|
98 | <b> |
---|
99 | <pre> |
---|
100 | ... |
---|
101 | ... ${JAVAPACKAGE} ... |
---|
102 | ... |
---|
103 | </pre> |
---|
104 | </b> |
---|
105 | </font> |
---|
106 | |
---|
107 | <blockquote> |
---|
108 | <i> |
---|
109 | (please note the <b>${..}</b> syntax with required braces around the |
---|
110 | variable name) |
---|
111 | </i> |
---|
112 | </blockquote> |
---|
113 | |
---|
114 | <p>You have probably already understood that CMT provides internal |
---|
115 | predefined similar <a href="CMTDoc.html#Standard templates for makefile fragments">variable names</a> |
---|
116 | |
---|
117 | <p>the typical example being <b>CONSTITUENT</b> which is replaced by the |
---|
118 | constituent name when the fragment is instanciated. |
---|
119 | |
---|
120 | <p>What I'm talking about here consists in adding any number of |
---|
121 | user-defined variables which value will be specified on the <b>document</b> |
---|
122 | statement line using any number of <b><variable-name>=<value></b> constructs. |
---|
123 | |
---|
124 | <p>You will notice that the all-uppercase convention has been selected |
---|
125 | for CMT-internal variables (eg. <b>CONSTITUENT</b>). This is why I have used |
---|
126 | this convention for this example. This is only a convention, any form |
---|
127 | is possible here. The only constraint being that it should not overlap |
---|
128 | with a macro name or an env. var name. |
---|
129 | |
---|
130 | <hr> |
---|
131 | <h1><a name="Accessing packages in a sub-directory"/>Accessing packages in a sub-directory</h1> |
---|
132 | |
---|
133 | <blockquote><i> |
---|
134 | <p>I tried to use CMT with sub-packages. How does this work? If I |
---|
135 | have on cvs a structure like |
---|
136 | |
---|
137 | <font face="courier new, courier" COLOR="#770077"> |
---|
138 | <b> |
---|
139 | <pre> |
---|
140 | Velo/VeloEvent/.. |
---|
141 | /VSicbCnv/.. |
---|
142 | </pre> |
---|
143 | </b> |
---|
144 | </font> |
---|
145 | |
---|
146 | <p>and on disk: |
---|
147 | |
---|
148 | <font face="courier new, courier" COLOR="#770077"> |
---|
149 | <b> |
---|
150 | <pre> |
---|
151 | Velo/VeloEvent/v3/.. |
---|
152 | /VSicbCnv/v3/.. |
---|
153 | </pre> |
---|
154 | </b> |
---|
155 | </font> |
---|
156 | |
---|
157 | <p> it recognizes the stuff in the use statement, but when I say |
---|
158 | <b>cmt show packages</b> they are not there... Hence, the |
---|
159 | add-in for devstudio fails. |
---|
160 | </i></blockquote> |
---|
161 | |
---|
162 | <p>Well this is just a subtle effect : |
---|
163 | |
---|
164 | <ul> |
---|
165 | <li> when you are in the context of say <b>VeloEvent/v3</b>, |
---|
166 | then the path of the current package is implicitly added to the |
---|
167 | search path, all the used packages that reside in this same root |
---|
168 | are visible (which explains that the <b>cmt show uses</b> |
---|
169 | works). |
---|
170 | |
---|
171 | <li> but, when you ask for <b>cmt show packages</b>, this is |
---|
172 | performed outside of any context (mainly because it can be done |
---|
173 | from any location). Then only packages reachable in the search |
---|
174 | path (ie. <b>CMTPATH</b> or in the <b>CMT\path</b> registry set) |
---|
175 | are visible. |
---|
176 | </ul> |
---|
177 | |
---|
178 | <p>Then in your precise case, you can do one of the following : |
---|
179 | |
---|
180 | <ol> |
---|
181 | |
---|
182 | <li>If you strictly have (as you explained) |
---|
183 | |
---|
184 | <font face="courier new, courier" COLOR="#770077"> |
---|
185 | <b> |
---|
186 | <pre> |
---|
187 | xxx/Velo/VeloEvent/v3/.. |
---|
188 | /VSicbCnv/v3/.. |
---|
189 | </pre> |
---|
190 | </b> |
---|
191 | </font> |
---|
192 | |
---|
193 | <p>then the <b>CMTPATH</b> should include <b>xxx/Velo</b> in |
---|
194 | order to make both <b>VeloEvent</b> and <b>VSicbCnv</b> |
---|
195 | visible. |
---|
196 | |
---|
197 | <li> If <b>Velo</b> is itself a package : |
---|
198 | |
---|
199 | <font face="courier new, courier" COLOR="#770077"> |
---|
200 | <b> |
---|
201 | <pre> |
---|
202 | xxx/Velo/VeloEvent/v3/.. |
---|
203 | /VSicbCnv/v3/.. |
---|
204 | /v1/... |
---|
205 | </pre> |
---|
206 | </b> |
---|
207 | </font> |
---|
208 | |
---|
209 | <p>then the <b>CMTPATH</b> may simply include <b>xxx</b> |
---|
210 | (although <b>xxx/Velo</b> is possible too but in this case, it |
---|
211 | is redundent). This makes all packages below <b>Velo</b> |
---|
212 | visible. |
---|
213 | |
---|
214 | </ol> |
---|
215 | |
---|
216 | <p>The difference between 1) and 2) is really the fact that in 2) |
---|
217 | <b>Velo</b> IS a true <b>CMT</b> package, whereas, in 1) |
---|
218 | <b>Velo</b> is just a prefix. |
---|
219 | |
---|
220 | <p>For simple efficiency reasons, <b>CMT</b> does not scan any |
---|
221 | arbitrary directory tree depth when it looks for all packages, but |
---|
222 | only the tree of true <b>CMT</b> packages + one level below each |
---|
223 | package. |
---|
224 | |
---|
225 | <hr> |
---|
226 | <address><a href="mailto:arnault@lal.in2p3.fr">Christian Arnault</a></address> |
---|
227 | <!-- Created: Thu Oct 26 09:09:01 MET DST 2000 --> |
---|
228 | <!-- hhmts start --> |
---|
229 | Last modified: Thu Nov 9 15:16:35 MET 2000 |
---|
230 | <!-- hhmts end --> |
---|
231 | </body> |
---|
232 | </html> |
---|