Skip to content

Commit 786da76

Browse files
jwakelyjwakely
committed
Modernize instructions in how-to-docs.html
1 parent fd5e251 commit 786da76

File tree

1 file changed

+56
-43
lines changed

1 file changed

+56
-43
lines changed

‎how-to-docs.html‎

Lines changed: 56 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -8,75 +8,87 @@
88

99
<body>
1010

11-
<p>Revised:
12-
<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B %Y" startspan -->24 March 2023<!--webbot bot="Timestamp" endspan i-checksum="39626" --></p>
11+
<p>Revised:
12+
2 November 2024</p>
1313

1414
<h1>How To Instructions</h1>
15-
<p>These instruction assume you going to keep the issues lists source files in a directory named &quot;issues&quot;,
16-
and the issues lists generated HTML files in a directory named &quot;issues-gh-pages&quot;.</p>
17-
<blockquote>
18-
<p>Keeping the source files and generated HTML files in separate directories
19-
falls out from the GitHub automatic web page approach: files in a branch named &quot;gh-pages&quot;
20-
are automatically published by GitHub as web pages.</p>
21-
</blockquote>
15+
<p>These instruction assume you going to keep the issues lists source files in a directory named &quot;issues&quot;.
16+
The issues are stored in XML files, one file per issue.
17+
The software in the <code>src</code> directory builds programs
18+
that read the XML files and generates the HTML issues lists.
19+
When changes to the XML files are pushed to the GitHub repository an automated
20+
<a href="https://docs.github.com/en/actions">GitHub Actions</a> workflow
21+
generates new HTML files and commits them to the <code>gh-pages</code> branch.
22+
The content of the <code>gh-pages</code> branch is automatically deployed
23+
to <a href="https://cplusplus.github.io/LWG/">https://cplusplus.github.io/LWG/</a>.
24+
</p>
2225

2326
<h2>Prerequisites</h2>
2427
<ul>
2528
<li>Git</li>
2629
<li>A C++17 compiler. Clang 9 works. GCC 8.x works for unix-like systems, but GCC 9.3 is recommended (because its <code>std::filesystem</code> supports Windows, and no additional <code>-lstdc++fs</code> linker option is needed).</li>
2730
<li>Windows is a prerequisite to use the Windows <code>.bat</code> scripts, or
28-
a POSIX environment is a prerequisite to use the equivalent <code>.sh</code>
29-
scripts.</li>
31+
a POSIX environment is a prerequisite to use the equivalent <code>make</code>
32+
commands.</li>
3033
</ul>
3134

3235
<h2>Initial setup</h2>
3336
<p><b>Do this once only:</b></p>
3437
<blockquote>
3538
<pre>cd path-to-where-you-want-to-keep-this-stuff
3639
git clone [email protected]:cplusplus/LWG.git issues
37-
git clone -b gh-pages [email protected]:cplusplus/LWG.git issues-gh-pages
38-
cd issues
39-
mkdir mailing</pre>
40+
</pre>
4041
</blockquote>
41-
<p>Using recent versions of Git the second <code>git clone</code> command
42-
can be replaced by adding a new "worktree" that shares the repository metadata
43-
with the initial clone:</p>
44-
<blockquote><pre>
45-
git -C issues worktree add -b gh-pages ../issues-gh-pages origin/gh-pages
46-
</pre></blockquote>
47-
<p>This has the advantage of only cloning the repo once,
48-
which saves time, bandwidth and disk space.</p>
49-
42+
<p>
43+
The commands shown below assume you are in the <code>issues</code> directory
44+
that contains the git repository cloned by the command above.
45+
</p>
46+
<p>
47+
The repository contains a <code>Makefile</code> that has recipes for
48+
building the software (<code>make pgms</code>),
49+
updating the meta-data (<code>make new-papers</code> etc.),
50+
and regenerating the HTML lists (<code>make lists</code>).
51+
</p>
5052

51-
<h2>Build issues software</h2>
52-
<p>Do this after the initial setup, and then again whenever the source
53-
code (in <code>issues/src</code>) changes.</p>
53+
<h2>Working with the issues lists on Windows</h2>
54+
<p>
55+
If you can't use <code>make</code> then the steps are a little more manual:
56+
</p>
5457
<blockquote>
55-
<pre>cd issues
56-
bin\build_pgms</pre>
57-
</blockquote>
58+
<pre>cd issues
59+
mkdir mailing
60+
bin\build_pgms
61+
bin\build_lists
62+
</pre></blockquote>
63+
<p>
64+
You will need to re-run <code>bin\build_pgms</code>
65+
whenever the source code (in <code>issues/src</code>) changes.
66+
(This isn't needed when using <code>make</code> because the makefile
67+
will automatically do <code>make pgms</code> as a prerequisite of
68+
<code>make lists</code>.)
69+
</p>
5870

5971
<h2>Add or change issues</h2>
6072
<p>There is one source file per issue, in <code>issues/xml</code>. The file
61-
<code>issues/xml/lwg-template.xml</code> can be used as a template to start a
73+
<code>issues/xml/lwg-template.xml</code> can be used as a template to start a
6274
new issue. Use any text editor to edit the files.</p>
6375
<p>Commit files locally as you update them:</p>
6476
<blockquote>
65-
<pre>cd issues\xml
66-
edit-as-needed
67-
git commit -a -m&quot;your commit message here&quot;</pre>
68-
</blockquote>
69-
<p>Verify your changes had the desired effect by regenerating the
70-
issues lists and inspecting your changes:</p>
71-
<blockquote>
72-
<pre>cd issues
73-
bin\build_lists</pre>
77+
<pre>cd xml
78+
<em># edit the XML files or add new XML files</em>
79+
<em># ...</em>
80+
<em># stage the edited XML files (and any new ones) to be committed:</em>
81+
git add xml/issues*.xml
82+
git commit -m &quot;your commit message here&quot;</pre>
7483
</blockquote>
75-
<p>Once you are happy with your changes, push them up to the GitHub
84+
<p>Verify your changes had the desired effect by regenerating the
85+
issues lists and inspecting your changes, by running
86+
<code>make lists</code> (or <code>bin\build_lists</code> on Windows).
87+
</p>
88+
<p>Once you are happy with your changes, push them up to the GitHub
7689
public repository:</p>
7790
<blockquote>
78-
<pre>cd issues
79-
git push</pre>
91+
<pre>git push</pre>
8092
</blockquote>
8193
<p>New versions of the issues lists will be automatically published online.</p>
8294

@@ -155,7 +167,8 @@ <h2>Generate Issues Lists for a Mailing</h2>
155167
<ol>
156168
<li>The revision history (this should be done first)
157169
<ol>
158-
<li>Run <code>bin/lists revision history</code> to print the new revision history.</li>
170+
<li>Run <code>make history</code> (or equivalently, <code>bin/lists revision history</code>)
171+
to print the new revision history.</li>
159172
<li>Paste the new revision under the <code>&lt;revision_history&gt;</code> tag</li>
160173
</ol>
161174
</li>

0 commit comments

Comments
 (0)