Skip to content

Commit e5b3310

Browse files
jwakelyCaseyCarter
jwakely
and
CaseyCarter
authored
Modernize instructions in how-to-docs.html (#441)
* Modernize instructions in how-to-docs.html Co-authored-by: Casey Carter <[email protected]>
1 parent e03efc6 commit e5b3310

File tree

1 file changed

+56
-45
lines changed

1 file changed

+56
-45
lines changed

‎how-to-docs.html

Lines changed: 56 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -8,75 +8,85 @@
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 instructions assume you keep the issues lists source files in a directory named <code>issues</code>.
16+
Each issue is stored in an XML file.
17+
The code in <code>src</code> generates the HTML issues lists from the XML sources.
18+
When changes to the XML files are pushed to the GitHub repository an automated
19+
<a href="https://docs.github.com/en/actions">GitHub Actions</a> workflow
20+
generates new HTML files and commits them to the <code>gh-pages</code> branch.
21+
The content of the <code>gh-pages</code> branch is automatically deployed
22+
to <a href="https://cplusplus.github.io/LWG/">https://cplusplus.github.io/LWG/</a>.
23+
</p>
2224

2325
<h2>Prerequisites</h2>
2426
<ul>
2527
<li>Git</li>
2628
<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>
27-
<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>
29+
<li>Windows is a prerequisite to use the Windows <code>.bat</code> scripts;
30+
a POSIX environment is a prerequisite to use the equivalent <code>make</code>
31+
commands.</li>
3032
</ul>
3133

3234
<h2>Initial setup</h2>
3335
<p><b>Do this once only:</b></p>
3436
<blockquote>
3537
<pre>cd path-to-where-you-want-to-keep-this-stuff
3638
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>
39+
</pre>
4040
</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-
41+
<p>
42+
The commands shown below assume you are in the <code>issues</code> directory
43+
that contains the git repository cloned by the command above.
44+
</p>
45+
<p>
46+
The repository contains a <code>Makefile</code> that has recipes for
47+
building the software (<code>make pgms</code>),
48+
updating the meta-data (<code>make new-papers</code> etc.),
49+
and regenerating the HTML lists (<code>make lists</code>).
50+
</p>
5051

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>
52+
<h2>Working with the issues lists on Windows</h2>
53+
<p>
54+
If you can't use <code>make</code> then the steps are a little more manual:
55+
</p>
5456
<blockquote>
55-
<pre>cd issues
56-
bin\build_pgms</pre>
57-
</blockquote>
57+
<pre>cd issues
58+
mkdir mailing
59+
bin\build_pgms
60+
bin\build_lists
61+
</pre></blockquote>
62+
<p>
63+
You will need to re-run <code>bin\build_pgms</code>
64+
whenever the source code (in <code>issues/src</code>) changes.
65+
(This isn't needed when using <code>make</code> because the makefile
66+
will automatically do <code>make pgms</code> as a prerequisite of
67+
<code>make lists</code>.)
68+
</p>
5869

5970
<h2>Add or change issues</h2>
6071
<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
62-
new issue. Use any text editor to edit the files.</p>
72+
<code>issues/xml/lwg-template.xml</code> is a template for a
73+
new issue.</p>
6374
<p>Commit files locally as you update them:</p>
6475
<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>
76+
<pre><em># edit the XML files or add new XML files</em>
77+
<em># ...</em>
78+
<em># stage the edited XML files (and any new ones) to be committed:</em>
79+
git add xml/issues*.xml
80+
git commit -m "your commit message here"</pre>
7481
</blockquote>
75-
<p>Once you are happy with your changes, push them up to the GitHub
82+
<p>Verify your changes had the desired effect by regenerating the
83+
issues lists and inspecting your changes, by running
84+
<code>make lists</code> (or <code>bin\build_lists</code> on Windows).
85+
</p>
86+
<p>Once you are happy with your changes, push them up to the GitHub
7687
public repository:</p>
7788
<blockquote>
78-
<pre>cd issues
79-
git push</pre>
89+
<pre>git push</pre>
8090
</blockquote>
8191
<p>New versions of the issues lists will be automatically published online.</p>
8292

@@ -155,7 +165,8 @@ <h2>Generate Issues Lists for a Mailing</h2>
155165
<ol>
156166
<li>The revision history (this should be done first)
157167
<ol>
158-
<li>Run <code>bin/lists revision history</code> to print the new revision history.</li>
168+
<li>Run <code>make history</code> (or equivalently, <code>bin/lists revision history</code>)
169+
to print the new revision history.</li>
159170
<li>Paste the new revision under the <code>&lt;revision_history&gt;</code> tag</li>
160171
</ol>
161172
</li>

0 commit comments

Comments
 (0)