-
Notifications
You must be signed in to change notification settings - Fork 1
/
mkproject_create.sthlp
143 lines (115 loc) · 5.09 KB
/
mkproject_create.sthlp
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
{smcl}
{* *! version 2.1.3}{...}
{vieweralsosee "boilerplate" "help boilerplate"}{...}
{vieweralsosee "mkproject" "help mkproject"}{...}
{viewerjumpto "Syntax" "mkproject##syntax"}{...}
{viewerjumpto "Description" "mkproject##description"}{...}
{viewerjumpto "Example" "mkproject##example"}{...}
{title:Title}
{phang}
{bf:mkproject, create} {hline 2} Create new templates for the {cmd:mkproject} command.
{title:Description}
{pstd}To create a new template you are going to create a text file with two
parts:{p_end}
{pmore}a part within the {cmd:<header>} and {cmd:</header>} tags containing
meta-data, like a label, and{p_end}
{pmore}a part within the {cmd:<body>} and {cmd:</body>} tags containing the
actual steps you want {cmd:mkproject} to take when creating a new project.{p_end}
{pstd} After creating that file you type in Stata
{cmd:mkproject, create(}{it:that_text_file}{cmd:)}. Based on that text file
{cmd:mkproject} will create the template, and the corresponding help file.
{pstd}
This template is going to be used at three times when {cmd:mkproject} makes a
project folder:
{pmore}
First, {cmd:mkproject} creates the project folder, and any sub-folders specified
in the template. It changes the current working directory to the project folder.
{pmore}
Second, {cmd:mkproject} creates any files specified in the template, using
{help boilerplate}.
{pmore}
Third, {cmd:mkproject} executes any commands specified in the template.
{pstd}
So a template should tell {cmd:mkproject} what subdirectories it needs to create,
what files it needs to create, and what commands it needs to execute. On top of
that you can add various meta-data in the header.
{pstd}
Lets look at an example. Below is the template for {help mp_p_course:course}.
You can look at the source code for any template by typing {cmd:mkproject, query},
click on any template you are interested in, that opens a help-file, and at the
bottom there is a link that will show the source code for that template in the
viewer.
--------------- begin template -------------------
{cmd}{...}
<header>
<mkproject> project
<version> 2.1.2
<label> Small research project as part of a course
<reqs> dirtree
<description>
{c -(}pstd{c )-}
This template is for a small research project that takes place over a
short period of time that does not require snapshots. A typical example
would be a project someone has to do for a course.
</description>
</header>
<body>
<dir> docu
<dir> data
<dir> ana
<dir> txt
<file> rlogc docu/research_log.md
<file> main ana/<abbrev>_main.do
<file> dta_c ana/<abbrev>_dta01.do
<file> ana ana/<abbrev>_ana01.do
<cmd> dirtree
</body>
{txt}{...}
-------------- end template --------------------
{pstd}
Lines between {cmd:<header>} and {cmd:</header>} contain
meta-information, like the label for that template.
{pstd}
Within the header you can add five types of meta-data:
{pmore}
{cmd:<mkproject>} Indicates that this is a template, and the word after it can
be either {cmd:project} or {cmd:boilerplate}, to indicate whether this is a
{cmd:mkproject} or {cmd:boilerplate} template. You can specify it in your text
file or if you don't specify it, {cmd:mkproject, create()} will add it for you.
{pmore}
{cmd:<version>} Indicates which version of {cmd:mkproject} is used to create this
template. {cmd:mkproject} uses that information to ensure backwards compatability;
if a new version of {cmd:mkproject} becomes available, you can install that
without fearing that it will break your older templates. You can specify it
yourself, or if you don't specify it, {cmd:mkproject, create()} will set it to
the current version of {cmd:mkproject}
{pmore}
{cmd:<label>} gives the short description of your template, that will be shown
with {cmd:mkproject, query}
{pmore}
{cmd:<reqs>} specifies a community contributed package that is required for this
template. If any of the {cmd:boilerplate} templates used in the {cmd:<file>}
tag have a requirement, then that will be automatically copied here by
{cmd:mkproject, create()}.
{pmore}
The lines between {cmd:<description>} and {cmd:</description>} give a longer
description of the template as it will appear in the help-fearing. It may contain
{help smcl} tags.
{pstd}
Within the {cmd:<body>} and {cmd:</body>} tags is the actual template:
{pstd}
Lines starting with {cmd:<dir>} tell you what sub-directories that template will
create
{pstd}
Lines starting with {cmd:<file>} have two elements, the first "word" is the name
of the template that {help boilerplate} will use to create a file, and the second
"word" is the filename. This filename can contain the tag {cmd:<abbrev>} which
{cmd:mkproject} will replace with the {it:proj_abbrev} you will specify when using
{cmd:mkproject} to create a project folder.
{pstd}
Lines starting with {cmd:<cmd>} tell you what commands {cmd:mkproject} will run
after creating those directories and files
{pstd}
In practice, the easiest way to create a new template is usually to look for a
template that is close to what you want, and copy and adapt the source of that
template.