From a751a50cb66add5419bd059aa2905cb773420e0a Mon Sep 17 00:00:00 2001 From: Jonathan Wakely Date: Sat, 2 Nov 2024 13:21:10 +0000 Subject: [PATCH 1/9] Modernize instructions in how-to-docs.html --- how-to-docs.html | 99 +++++++++++++++++++++++++++--------------------- 1 file changed, 56 insertions(+), 43 deletions(-) diff --git a/how-to-docs.html b/how-to-docs.html index cbccba9b47..63a4c2ba95 100644 --- a/how-to-docs.html +++ b/how-to-docs.html @@ -8,25 +8,28 @@ -

Revised: -24 March 2023

+

Revised: +2 November 2024

How To Instructions

-

These instruction assume you going to keep the issues lists source files in a directory named "issues", -and the issues lists generated HTML files in a directory named "issues-gh-pages".

-
-

Keeping the source files and generated HTML files in separate directories -falls out from the GitHub automatic web page approach: files in a branch named "gh-pages" -are automatically published by GitHub as web pages.

-
+

These instruction assume you going to keep the issues lists source files in a directory named "issues". +The issues are stored in XML files, one file per issue. +The software in the src directory builds programs +that read the XML files and generates the HTML issues lists. +When changes to the XML files are pushed to the GitHub repository an automated +GitHub Actions workflow +generates new HTML files and commits them to the gh-pages branch. +The content of the gh-pages branch is automatically deployed +to https://cplusplus.github.io/LWG/. +

Prerequisites

Initial setup

@@ -34,49 +37,58 @@

Initial setup

cd path-to-where-you-want-to-keep-this-stuff
 git clone git@github.com:cplusplus/LWG.git issues
-git clone -b gh-pages git@github.com:cplusplus/LWG.git issues-gh-pages
-cd issues
-mkdir mailing
+
-

Using recent versions of Git the second git clone command -can be replaced by adding a new "worktree" that shares the repository metadata -with the initial clone:

-
-git -C issues worktree add -b gh-pages ../issues-gh-pages origin/gh-pages
-
-

This has the advantage of only cloning the repo once, -which saves time, bandwidth and disk space.

- +

+The commands shown below assume you are in the issues directory +that contains the git repository cloned by the command above. +

+

+The repository contains a Makefile that has recipes for +building the software (make pgms), +updating the meta-data (make new-papers etc.), +and regenerating the HTML lists (make lists). +

-

Build issues software

-

Do this after the initial setup, and then again whenever the source -code (in issues/src) changes.

+

Working with the issues lists on Windows

+

+If you can't use make then the steps are a little more manual: +

- 
cd issues
-bin\build_pgms
-
+
cd issues
+mkdir mailing
+bin\build_pgms
+bin\build_lists
+
+

+You will need to re-run bin\build_pgms +whenever the source code (in issues/src) changes. +(This isn't needed when using make because the makefile +will automatically do make pgms as a prerequisite of +make lists.) +

Add or change issues

There is one source file per issue, in issues/xml. The file -issues/xml/lwg-template.xml can be used as a template to start a +issues/xml/lwg-template.xml can be used as a template to start a new issue. Use any text editor to edit the files.

Commit files locally as you update them:

- 
cd issues\xml
-edit-as-needed
-git commit -a -m"your commit message here"
-
-

Verify your changes had the desired effect by regenerating the -issues lists and inspecting your changes:

-
- 
cd issues
-bin\build_lists
+ 
cd xml
+# edit the XML files or add new XML files
+# ...
+# stage the edited XML files (and any new ones) to be committed:
+git add xml/issues*.xml
+git commit -m "your commit message here"
-

Once you are happy with your changes, push them up to the GitHub +

Verify your changes had the desired effect by regenerating the +issues lists and inspecting your changes, by running +make lists (or bin\build_lists on Windows). +

+

Once you are happy with your changes, push them up to the GitHub public repository:

- 
cd issues
-git push
+ 
git push

New versions of the issues lists will be automatically published online.

@@ -155,7 +167,8 @@

Generate Issues Lists for a Mailing

  1. The revision history (this should be done first)
      -
    1. Run bin/lists revision history to print the new revision history.
      2. +
    2. Run make history (or equivalently, bin/lists revision history) + to print the new revision history.
    3. Paste the new revision under the <revision_history> tag
    2. From e6ed923e4ef31579b1f7f624b926f67e65df449d Mon Sep 17 00:00:00 2001 From: Jonathan Wakely Date: Sat, 2 Nov 2024 19:13:07 +0000 Subject: [PATCH 2/9] Update how-to-docs.html Co-authored-by: Casey Carter --- how-to-docs.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/how-to-docs.html b/how-to-docs.html index 63a4c2ba95..dc02a62df8 100644 --- a/how-to-docs.html +++ b/how-to-docs.html @@ -12,7 +12,7 @@ 2 November 2024

    How To Instructions

    -

    These instruction assume you going to keep the issues lists source files in a directory named "issues". +

    These instructions assume you keep the issues lists source files in a directory named issues. The issues are stored in XML files, one file per issue. The software in the src directory builds programs that read the XML files and generates the HTML issues lists. From 398af839bfac19052756b30856fca852777a9327 Mon Sep 17 00:00:00 2001 From: Jonathan Wakely Date: Sat, 2 Nov 2024 19:13:17 +0000 Subject: [PATCH 3/9] Update how-to-docs.html Co-authored-by: Casey Carter --- how-to-docs.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/how-to-docs.html b/how-to-docs.html index dc02a62df8..6caefcd656 100644 --- a/how-to-docs.html +++ b/how-to-docs.html @@ -13,7 +13,7 @@

    How To Instructions

    These instructions assume you keep the issues lists source files in a directory named issues. -The issues are stored in XML files, one file per issue. +Each issue is stored in an XML file. The software in the src directory builds programs that read the XML files and generates the HTML issues lists. When changes to the XML files are pushed to the GitHub repository an automated From 5f00f5d6333ec1a7c24fe643c476a52207465367 Mon Sep 17 00:00:00 2001 From: Jonathan Wakely Date: Sat, 2 Nov 2024 19:13:49 +0000 Subject: [PATCH 4/9] Update how-to-docs.html Co-authored-by: Casey Carter --- how-to-docs.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/how-to-docs.html b/how-to-docs.html index 6caefcd656..15bf9608dc 100644 --- a/how-to-docs.html +++ b/how-to-docs.html @@ -27,7 +27,7 @@

    Prerequisites

    • Git
    • A C++17 compiler. Clang 9 works. GCC 8.x works for unix-like systems, but GCC 9.3 is recommended (because its std::filesystem supports Windows, and no additional -lstdc++fs linker option is needed).
      • -
    • Windows is a prerequisite to use the Windows .bat scripts, or +
    • Windows is a prerequisite to use the Windows .bat scripts; a POSIX environment is a prerequisite to use the equivalent make commands.
    From 6cf4107d0d6d8a1730f920e45ffbd304f3d23dc2 Mon Sep 17 00:00:00 2001 From: Jonathan Wakely Date: Sat, 2 Nov 2024 19:14:07 +0000 Subject: [PATCH 5/9] Update how-to-docs.html Co-authored-by: Casey Carter --- how-to-docs.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/how-to-docs.html b/how-to-docs.html index 15bf9608dc..003e01d414 100644 --- a/how-to-docs.html +++ b/how-to-docs.html @@ -70,7 +70,7 @@

    Working with the issues lists on Windows

    Add or change issues

    There is one source file per issue, in issues/xml. The file -issues/xml/lwg-template.xml can be used as a template to start a +issues/xml/lwg-template.xml is a template for a new issue. Use any text editor to edit the files.

    Commit files locally as you update them:

    From 27060df3c70a324ac3f5cd42779ce028318c4802 Mon Sep 17 00:00:00 2001 From: Jonathan Wakely Date: Sat, 2 Nov 2024 19:14:22 +0000 Subject: [PATCH 6/9] Update how-to-docs.html Co-authored-by: Casey Carter --- how-to-docs.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/how-to-docs.html b/how-to-docs.html index 003e01d414..4cd3912a11 100644 --- a/how-to-docs.html +++ b/how-to-docs.html @@ -71,7 +71,7 @@

    Working with the issues lists on Windows

    Add or change issues

    There is one source file per issue, in issues/xml. The file issues/xml/lwg-template.xml is a template for a -new issue. Use any text editor to edit the files.

    +new issue.

    Commit files locally as you update them:

    cd xml

From 3f4b140bd8310f09542eec6da10f2f18e326555a Mon Sep 17 00:00:00 2001
From: Jonathan Wakely 
Date: Sat, 2 Nov 2024 19:14:39 +0000
Subject: [PATCH 7/9] Update how-to-docs.html

Co-authored-by: Casey Carter 
---
 how-to-docs.html | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/how-to-docs.html b/how-to-docs.html
index 4cd3912a11..c778374bcc 100644
--- a/how-to-docs.html
+++ b/how-to-docs.html
@@ -74,8 +74,7 @@ 
    Add or change issues
    
 new issue.
    
 
    Commit files locally as you update them:
    
 
    
-  
    cd xml
-# edit the XML files or add new XML files
+  
    # edit the XML files or add new XML files
 # ...
 # stage the edited XML files (and any new ones) to be committed:
 git add xml/issues*.xml

From 607082397425ee1e1d727c9467ae47280f7b9a6b Mon Sep 17 00:00:00 2001
From: Jonathan Wakely 
Date: Sat, 2 Nov 2024 19:15:45 +0000
Subject: [PATCH 8/9] Update how-to-docs.html

Co-authored-by: Casey Carter 
---
 how-to-docs.html | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/how-to-docs.html b/how-to-docs.html
index c778374bcc..10a2650b28 100644
--- a/how-to-docs.html
+++ b/how-to-docs.html
@@ -78,7 +78,7 @@ 
    Add or change issues
    
 # ...
 # stage the edited XML files (and any new ones) to be committed:
 git add xml/issues*.xml
-git commit -m "your commit message here"
    
+git commit -m "your commit message here"
    
 
    
 
    Verify your changes had the desired effect by regenerating the
 issues lists and inspecting your changes, by running

From c24e88c1529036c8b9b17a70fa36e934da71098b Mon Sep 17 00:00:00 2001
From: Jonathan Wakely 
Date: Sat, 2 Nov 2024 21:05:16 +0000
Subject: [PATCH 9/9] Update how-to-docs.html

Co-authored-by: Casey Carter 
---
 how-to-docs.html | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/how-to-docs.html b/how-to-docs.html
index 10a2650b28..4f280e75db 100644
--- a/how-to-docs.html
+++ b/how-to-docs.html
@@ -14,8 +14,7 @@
 
    How To Instructions
    
 
    These instructions assume you keep the issues lists source files in a directory named issues.
 Each issue is stored in an XML file.
-The software in the src directory builds programs
-that read the XML files and generates the HTML issues lists.
+The code in src generates the HTML issues lists from the XML sources.
 When changes to the XML files are pushed to the GitHub repository an automated
 GitHub Actions workflow
 generates new HTML files and commits them to the gh-pages branch.