source: CMT/v1r14p20031120/doc/CMTFAQ.html @ 1

Last change on this file since 1 was 1, checked in by arnault, 19 years ago

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