commit 312e9e3e6be5907fda1b51e04c943a2e3bcc8788
parent 507332742b255295849a879a3fb397bbad4819f6
Author: JayVii <jayvii[AT]posteo[DOT]de>
Date: Sat, 29 Jun 2024 20:18:07 +0200
feat: create summary from README via pandoc
Diffstat:
| D | README | | | 131 | ------------------------------------------------------------------------------- |
| A | README.md | | | 127 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| M | bin/git_update_repo_html.sh | | | 55 | +++++++++++++++++++++++++++++++------------------------ |
3 files changed, 158 insertions(+), 155 deletions(-)
diff --git a/README b/README
@@ -1,131 +0,0 @@
-Stagit - src.jayvii.de
-======================
-
-Please send patches or remarks to <jayvii[AT]posteo[DOT]de>
-
-Some scripts and assets to run https://src.jayvii.de
-
-Structure
----------
-
-|- bin/
-| |- git_create_repo.sh Creates A bare repository and HTML viewer
-| |- git_post_push.sh Used as post-push hook in repositories
-| |- git_post_push_all.sh Trigger post-update hook in all repositories
-| |- git_set_clone_url.sh Sets necessary URL to clone via http(s)
-| |- git_update_index_html.sh Updates the repository overview HTML page
-| |- git_update_repo_html.sh Updates the respository HTML viewer pages
-| '- git_update_repo.sh Updates git information to clone via http(s)
-|
-|- assets/
-| |- favicon.png Favicon and Logo of the page
-| |- backicon.png Logo for the "back" button in repos
-| |- style.css CSS for the HTML viewer
-| '- index.css CSS for the file index viewer
-|
-|- 404.html 404 Page
-|- index.html Index-Page for the Main site, redirects to /pub/
-|- .htaccess htaccess file with defaults for security
-'- .gitignore Files to be ignored when checking out git
-
-There are additional links for CSS and icon files.
-
-Syntax Highlighting
-===================
-
-The git_update_repo_html.sh script injects the highlight.tt HTML template into
-all files that could potentially show some code, i.e. all HTML files which are
-being generated within the "files/" sub-directory. The code within this
-injection calls additional CSS and javascript from the highlight.js project
-(https://highlightjs.org/).
-
-All associated assets (licensed under BSD-3-clause) are delivered within this
-repository and are only loaded when needed.
-
-Setup
-=====
-
-- Install https://www.codemadness.org/git/stagit/ on your Server
-- Use this template:
- git clone https://src.jayvii.de/pub/stagit-jayvii.de.git /var/www/git.myserver.com
-- Setup the HTML Root:
- mkdir -p /var/www/git.myserver.com/{pub,priv}
-- Setup git-user:
- useradd -r -m -U -d /var/www/git.myserver.com -s /bin/sh -G www-data git
-
-You can also create a "deployable.tar.gz" file with:
-
- make package
-
-You can find an up-do-date "deployable.tar.gz" and SHA256 file in the export of
-the remote repository.
-
-Private Repositories
---------------------
-
-Private repositories reside within prv/, while your public repositories
-are in pub/. Access to the private repositories is restricted via HTTP Basic
-Authentication
-(https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication).
-
-A .htaccess file is provided within the prv/ directory, however you also need
-to set up a user/password for the web-access, e.g. here for the user "username":
-
- sudo htpasswd -c /etc/apache2/.htpassword username
-
-Optional Tweaks
----------------
-
-Set your stagit server's URL via the "url" file:
-
- echo "https://src.example.com" > /var/www/src.example.com/url
-
-You may also setup SSH-credentials for the user or SSH-Auth keys.
-
-You most likely want to setup a webserver (e.g. Apache2) with "/var/www/
-git.myserver.com" (home of user "git") as its root-dir.
-
-As long as user "git" is in the group "www-data", file permissions should
-generally be no problem. For good measure, you may however still set up cron-job
-that enforces file permissions every now and then. In crontab, use following
-entries (assuming your git-folder is located in "/var/www/src.example.com"):
-
- 0 0 * * * chown git:www-data -R /var/www/src.example.com
- 0 0 * * * chmod 770 -R /var/www/src.example.com
-
-Examples
-========
-
-You'll find a post-update hook example in the "examples/hooks/" directory.
-
- examples/
- |
- '- hooks/
- |- post-update.sample1 Automatic packaging and deployment
- '- post-update.sample2 REUSE linting on push
-
-Further notes
-=============
-
-New repositories can be created via the webform in "/create_repo/index.html" or
-via an according GET request to that PHP-script:
-
- curl https://src.example.com/create_repo/?name=test_repo&description=this%20is%20just%20a%20test%20repository&owner=me&type=pub
-
-The "/create_repo/" endpoint is restricted to authenticated users via htaccess
-(just like the "/priv/" repositories). A GET request therefore has to supply the
-authentication credentials accordingly.
-
-License
-=======
-
-stagit-jayvii.de is licensed under AGPL-3.0-or-later.
-
-Bundled Assets
---------------
-
-favicon.png & backicon.png are modified versions of materialdesignicons and are
-licensed under Apache-2.0.
-
-stagit (https://www.codemadness.org/git/stagit) and some of its assets used here
-are licensed under MIT.
diff --git a/README.md b/README.md
@@ -0,0 +1,127 @@
+# Stagit - src.jayvii.de
+
+Please send patches or remarks to
+[jayvii[AT]posteo[DOT]de](mailto:jayvii[AT]poste[DOT]de)
+
+Some scripts and assets to run [src.jayvii.de](https://src.jayvii.de).
+
+## Structure
+
+```
+|- bin/
+| |- git_create_repo.sh Creates A bare repository and HTML viewer
+| |- git_post_push.sh Used as post-push hook in repositories
+| |- git_post_push_all.sh Trigger post-update hook in all repositories
+| |- git_set_clone_url.sh Sets necessary URL to clone via http(s)
+| |- git_update_index_html.sh Updates the repository overview HTML page
+| |- git_update_repo_html.sh Updates the respository HTML viewer pages
+| '- git_update_repo.sh Updates git information to clone via http(s)
+|
+|- assets/
+| |- favicon.png Favicon and Logo of the page
+| |- backicon.png Logo for the "back" button in repos
+| |- style.css CSS for the HTML viewer
+| '- index.css CSS for the file index viewer
+|
+|- 404.html 404 Page
+|- index.html Index-Page for the Main site, redirects to /pub/
+|- .htaccess htaccess file with defaults for security
+'- .gitignore Files to be ignored when checking out git
+```
+
+There are additional links for CSS and icon files.
+
+## Setup
+
+1. Install https://www.codemadness.org/git/stagit/ on your Server
+
+2. Use this template:
+
+```bash
+git clone https://src.jayvii.de/pub/stagit-jayvii.de.git /var/www/git.myserver.com
+```
+
+3. Setup the HTML Root:
+
+```bash
+mkdir -p /var/www/git.myserver.com/{pub,priv}
+```
+
+4. Setup git-user:
+
+```bash
+useradd -r -m -U -d /var/www/git.myserver.com -s /bin/sh -G www-data git
+```
+
+### Private Repositories
+
+Private repositories reside within `/prv`, while your public repositories
+are in `/pub`. Access to the private repositories is restricted via HTTP
+[Basic Authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication).
+
+A .htaccess file is provided within the `/prv` directory, however you also need
+to set up a user/password for the web-access, e.g. here for the user "username":
+
+```bash
+sudo htpasswd -c /etc/apache2/.htpassword username
+```
+
+### Optional Tweaks
+
+Set your stagit server's URL via the "url" file:
+
+```bash
+echo "https://src.example.com" > /var/www/src.example.com/url
+```
+
+You may also setup SSH-credentials for the user or SSH-Auth keys.
+
+You most likely want to setup a webserver (e.g. Apache2) with "/var/www/
+git.myserver.com" (home of user "git") as its root-dir.
+
+As long as user "git" is in the group "www-data", file permissions should
+generally be no problem. For good measure, you may however still set up cron-job
+that enforces file permissions every now and then. In crontab, use following
+entries (assuming your git-folder is located in "/var/www/src.example.com"):
+
+```cron
+0 0 * * * chown git:www-data -R /var/www/src.example.com
+0 0 * * * chmod 770 -R /var/www/src.example.com
+```
+
+## Examples
+
+You'll find a post-update hook example in the "examples/hooks/" directory.
+
+```
+examples/
+|
+'- hooks/
+ |- post-update.sample1 Automatic packaging and deployment
+ '- post-update.sample2 REUSE linting on push
+```
+
+## Further notes
+
+New repositories can be created via the webform in "/create_repo/index.html" or
+via an according GET request to that PHP-script:
+
+```bash
+curl https://src.example.com/create_repo/?name=test_repo&description=this%20is%20just%20a%20test%20repository&owner=me&type=pub
+```
+
+The "/create_repo/" endpoint is restricted to authenticated users via htaccess
+(just like the "/priv/" repositories). A GET request therefore has to supply the
+authentication credentials accordingly.
+
+## License
+
+stagit-jayvii.de is licensed under AGPL-3.0-or-later.
+
+### Bundled Assets
+
+favicon.png & backicon.png are modified versions of materialdesignicons and are
+licensed under Apache-2.0.
+
+stagit (https://www.codemadness.org/git/stagit) and some of its assets used here
+are licensed under MIT.
diff --git a/bin/git_update_repo_html.sh b/bin/git_update_repo_html.sh
@@ -45,11 +45,7 @@ if [ -f "${1}/${2}/${3}/index.html" ]; then
fi
## fetch repo description, URL and menu-line
-RDESCF=$(
- cat "${1}/${2}/${3}.git/description_full" 2>/dev/null | \
- sed -e 's/\//\\\//g'
-)
-RDESCS=$(
+RDESC=$(
cat "${1}/${2}/${3}.git/description" 2>/dev/null | \
sed -e 's/\//\\\//g'
)
@@ -66,7 +62,7 @@ THEAD=$(
cat "${1}/templates/head.html" | \
sed \
-e "s/<\!--TITLE-->/${3}/g" \
- -e "s/<\!--DESC-->/${RDESCS}/g" \
+ -e "s/<\!--DESC-->/${RDESC}/g" \
-e "s/<\!--DIR-->/\./g" \
-e "s/<\!--REPO-->/${RURL_ESC}/g"
)
@@ -74,25 +70,34 @@ TMENU=$(
cat "${1}/templates/menu.html" | \
sed \
-e "s/<\!--TITLE-->/${3}/g" \
- -e "s/<\!--DESC-->/${RDESCS}/g" \
+ -e "s/<\!--DESC-->/${RDESC}/g" \
-e "s/<\!--REPO-->/${RURL_ESC}/g" \
-e "s/<\!--MENU-->/${RMENU}/g"
)
-## if no full description exists, use the repository's readme
-if [ -z "$RDESCF" ]; then
- # find readme
- READMEFILE=$(
- find "${1}/${2}/${3}/file" -type f -name "*README*" | \
- head -n 1
+## re-format README to summary description
+# find readme
+READMEFILE=$(
+ find "${1}/${2}/${3}/file" -type f -name "*README*" | \
+ head -n 1
+)
+# if readme exists, re-format to summary description
+if [ ! -z "$READMEFILE" ]; then
+ RSUMD=$(
+ grep -E "<a\ href=\"#l[0-9]+\"\ class=\"line\"\ id=\"l[0-9]+\">" \
+ "$READMEFILE" | \
+ sed -E \
+ -e 's/^<a\ .*?<\/a>\s*//g' \
+ -e 's/ / /g' \
+ -e ' s/&/\&/g' \
+ -e 's/</\</g' \
+ -e 's/>/\>/g' \
+ -e 's/"/\"/g' \
+ -e 's/'/\'"'"'/g' \
+ -e 's/“/\"/g' \
+ -e 's/”/\"/g' | \
+ pandoc --to=html
)
- if [ ! -z "$READMEFILE" ]; then
- RDESCF=$(
- grep -E "<a\ href=\"#l[0-9]+\"\ class=\"line\"\ id=\"l[0-9]+\">" \
- "$READMEFILE" | \
- sed -E -e 's/^<a\ .*?<\/a>//g'
- )
- fi
fi
## Write template
@@ -103,7 +108,9 @@ ${THEAD}
${TMENU}
<div id=\"content\">
${ACTIVITY_HTML}
-<pre id=\"description\">${RDESCF}</pre>
+<div id=\"description\">
+${RSUMD}
+</div>
<hr>
<span>Clone this repository via:</span><br>
<span>git clone <a href=\"$RURL\">$RURL</a></span>
@@ -116,7 +123,7 @@ ${ACTIVITY_HTML}
# Exports Page -----------------------------------------------------------------
## fetch repo description, URL and menu-line
-RDESCS=$(
+RDESC=$(
cat "${1}/${2}/${3}.git/description" 2>/dev/null | \
sed -e 's/\//\\\//g'
)
@@ -134,7 +141,7 @@ THEAD=$(
cat "${1}/templates/head.html" | \
sed \
-e "s/<\!--TITLE-->/Exports\ -\ ${3}/g" \
- -e "s/<\!--DESC-->/${RDESCS}/g" \
+ -e "s/<\!--DESC-->/${RDESC}/g" \
-e "s/<\!--DIR-->/\./g" \
-e "s/<\!--REPO-->/${RURL}/g"
)
@@ -142,7 +149,7 @@ TMENU=$(
cat "${1}/templates/menu.html" | \
sed \
-e "s/<\!--TITLE-->/${3}/g" \
- -e "s/<\!--DESC-->/${RDESCS}/g" \
+ -e "s/<\!--DESC-->/${RDESC}/g" \
-e "s/<\!--REPO-->/${RURL}/g" \
-e "s/<\!--MENU-->/${RMENU}/g"
)
