Skip to content

Commit 9929d43

Browse files
sylvestresylvestre
committed
improve the rendering of the man pages
1 parent dc7e234 commit 9929d43

File tree

4 files changed

+179
-56
lines changed

4 files changed

+179
-56
lines changed

‎.github/workflows/website.yml‎

Lines changed: 8 additions & 56 deletions
Original file line numberDiff line numberDiff line change
@@ -68,62 +68,14 @@ jobs:
6868
6969
- name: Convert Manpages to HTML and Generate Index
7070
run: |
71-
mkdir -p manpages-html
72-
73-
# Convert manpages to HTML and collect names
74-
manpage_names=""
75-
for man in manpages/usr/local/share/man/man*/*.1; do
76-
if [ -f "$man" ]; then
77-
name=$(basename "$man" .1)
78-
man2html -r "$man" > "manpages-html/${name}.html"
79-
manpage_names="$manpage_names $name"
80-
fi
81-
done
82-
83-
# Generate index.html with links to all manpages
84-
cat > manpages-html/index.html << 'HEADER'
85-
<!DOCTYPE html>
86-
<html>
87-
<head>
88-
<meta charset="utf-8">
89-
<title>uutils coreutils - Manual Pages</title>
90-
<style>
91-
body { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif; max-width: 1200px; margin: 0 auto; padding: 20px; }
92-
h1 { color: #333; }
93-
.breadcrumb { margin-bottom: 20px; }
94-
.breadcrumb a { color: #007acc; text-decoration: none; }
95-
.breadcrumb a:hover { text-decoration: underline; }
96-
.manpage-grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(180px, 1fr)); gap: 15px; margin-top: 30px; }
97-
.manpage-link { display: block; padding: 12px; background: #f5f5f5; border: 1px solid #ddd; border-radius: 5px; text-decoration: none; color: #333; text-align: center; font-family: monospace; font-weight: bold; font-size: 1.1em; transition: all 0.3s ease; }
98-
.manpage-link:hover { background: #007acc; color: white; border-color: #007acc; transform: translateY(-2px); box-shadow: 0 2px 5px rgba(0,0,0,0.2); }
99-
@media (prefers-color-scheme: dark) {
100-
body { background: #1a1a1a; color: #e0e0e0; }
101-
h1 { color: #e0e0e0; }
102-
.manpage-link { background: #2a2a2a; border-color: #444; color: #e0e0e0; }
103-
.manpage-link:hover { background: #007acc; color: white; border-color: #007acc; }
104-
}
105-
</style>
106-
</head>
107-
<body>
108-
<div class="breadcrumb">
109-
<a href="/">Home</a> /
110-
<a href="/coreutils">Coreutils</a> /
111-
<span>Manual Pages</span>
112-
</div>
113-
<h1>Manual Pages</h1>
114-
<p>Complete manual pages for all uutils coreutils commands. Click on any command to view its full documentation.</p>
115-
<div class="manpage-grid">
116-
HEADER
117-
118-
for name in $(echo $manpage_names | tr ' ' '\n' | sort); do
119-
echo " <a href=\"${name}.html\" class=\"manpage-link\">${name}</a>" >> manpages-html/index.html
120-
done
121-
122-
cat >> manpages-html/index.html << 'FOOTER'
123-
</div>
124-
</body>
125-
</html>
126-
FOOTER
71+
# Extract tldr pages for examples
72+
mkdir -p tldr-pages
73+
if [ -f coreutils/docs/tldr.zip ]; then
74+
unzip -o coreutils/docs/tldr.zip -d tldr-extract
75+
find tldr-extract -name "*.md" -exec cp {} tldr-pages/ \;
76+
fi
77+
78+
uutils.github.io/scripts/build-manpages.sh manpages tldr-pages manpages-html uutils.github.io/templates
12779
12880
- name: Build Findutils Docs
12981
run: |

‎scripts/build-manpages.sh‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
#!/bin/bash
2+
# Build styled HTML manpages from man files
3+
# Usage: build-manpages.sh <manpages-dir> <tldr-dir> <output-dir> <templates-dir>
4+
5+
set -euo pipefail
6+
7+
MANPAGES_DIR="${1:?Usage: $0 <manpages-dir> <tldr-dir> <output-dir> <templates-dir>}"
8+
TLDR_DIR="${2:?}"
9+
OUTPUT_DIR="${3:?}"
10+
TEMPLATES_DIR="${4:?}"
11+
12+
mkdir -p "$OUTPUT_DIR"
13+
14+
MANPAGE_TEMPLATE="$TEMPLATES_DIR/manpage.html"
15+
INDEX_TEMPLATE="$TEMPLATES_DIR/manpage-index.html"
16+
17+
manpage_names=""
18+
19+
for man in "$MANPAGES_DIR"/usr/local/share/man/man*/*.1; do
20+
[ -f "$man" ] || continue
21+
name=$(basename "$man" .1)
22+
23+
# Convert manpage, strip man2html header and footer
24+
man_content=$(man2html -r "$man" | sed '1,/^$/d' | sed '/This document was created by/,/<\/BODY>/d; /<\/HTML>/d')
25+
26+
# Build tldr examples section
27+
tldr_html=""
28+
tldr_file="$TLDR_DIR/${name}.md"
29+
if [ -f "$tldr_file" ]; then
30+
tldr_html="<div class=\"tldr-section\"><h2>Examples (from tldr)</h2>"
31+
while IFS= read -r line; do
32+
case "$line" in
33+
"# "* | "> "* | "---" | "") ;;
34+
"- "*)
35+
desc="${line#- }"
36+
tldr_html="$tldr_html<div class=\"tldr-example\"><p class=\"tldr-desc\">$desc</p>"
37+
;;
38+
'`'*'`')
39+
cmd="${line#\`}"
40+
cmd="${cmd%\`}"
41+
cmd=$(echo "$cmd" | sed 's/&/\&amp;/g; s/</\&lt;/g; s/>/\&gt;/g')
42+
tldr_html="$tldr_html<pre><code>$cmd</code></pre></div>"
43+
;;
44+
esac
45+
done < "$tldr_file"
46+
tldr_html="$tldr_html</div>"
47+
fi
48+
49+
# Apply template: split at placeholders, concatenate with content
50+
# Get line numbers of placeholders
51+
content_line=$(grep -n '{{CONTENT}}' "$MANPAGE_TEMPLATE" | cut -d: -f1)
52+
tldr_line=$(grep -n '{{TLDR}}' "$MANPAGE_TEMPLATE" | cut -d: -f1)
53+
54+
{
55+
# Before {{CONTENT}}
56+
head -n $((content_line - 1)) "$MANPAGE_TEMPLATE" | sed "s|{{NAME}}|${name}|g"
57+
# The manpage content
58+
echo "$man_content"
59+
# Between {{CONTENT}} and {{TLDR}}
60+
sed -n "$((content_line + 1)),$((tldr_line - 1))p" "$MANPAGE_TEMPLATE" | sed "s|{{NAME}}|${name}|g"
61+
# The tldr content
62+
echo "$tldr_html"
63+
# After {{TLDR}}
64+
tail -n +$((tldr_line + 1)) "$MANPAGE_TEMPLATE" | sed "s|{{NAME}}|${name}|g"
65+
} > "$OUTPUT_DIR/${name}.html"
66+
67+
manpage_names="$manpage_names $name"
68+
done
69+
70+
# Build index page
71+
content_line=$(grep -n '{{LINKS}}' "$INDEX_TEMPLATE" | cut -d: -f1)
72+
{
73+
head -n $((content_line - 1)) "$INDEX_TEMPLATE"
74+
for name in $(echo $manpage_names | tr ' ' '\n' | sort); do
75+
echo " <a href=\"${name}.html\" class=\"manpage-link\">${name}</a>"
76+
done
77+
tail -n +$((content_line + 1)) "$INDEX_TEMPLATE"
78+
} > "$OUTPUT_DIR/index.html"
79+
80+
echo "Built $(echo $manpage_names | wc -w) manpages in $OUTPUT_DIR"

‎templates/manpage-index.html‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
<!DOCTYPE html>
2+
<html>
3+
<head>
4+
<meta charset="utf-8">
5+
<title>uutils coreutils - Manual Pages</title>
6+
<style>
7+
body { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif; max-width: 1200px; margin: 0 auto; padding: 20px; }
8+
h1 { color: #333; }
9+
.breadcrumb { margin-bottom: 20px; }
10+
.breadcrumb a { color: #007acc; text-decoration: none; }
11+
.breadcrumb a:hover { text-decoration: underline; }
12+
.manpage-grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(180px, 1fr)); gap: 15px; margin-top: 30px; }
13+
.manpage-link { display: block; padding: 12px; background: #f5f5f5; border: 1px solid #ddd; border-radius: 5px; text-decoration: none; color: #333; text-align: center; font-family: monospace; font-weight: bold; font-size: 1.1em; transition: all 0.3s ease; }
14+
.manpage-link:hover { background: #007acc; color: white; border-color: #007acc; transform: translateY(-2px); box-shadow: 0 2px 5px rgba(0,0,0,0.2); }
15+
@media (prefers-color-scheme: dark) {
16+
body { background: #1a1a1a; color: #e0e0e0; }
17+
h1 { color: #e0e0e0; }
18+
.manpage-link { background: #2a2a2a; border-color: #444; color: #e0e0e0; }
19+
.manpage-link:hover { background: #007acc; color: white; border-color: #007acc; }
20+
}
21+
</style>
22+
</head>
23+
<body>
24+
<div class="breadcrumb">
25+
<a href="/">Home</a> /
26+
<a href="/coreutils">Coreutils</a> /
27+
<span>Manual Pages</span>
28+
</div>
29+
<h1>Manual Pages</h1>
30+
<p>Complete manual pages for all uutils coreutils commands. Click on any command to view its full documentation.</p>
31+
<div class="manpage-grid">
32+
{{LINKS}}
33+
</div>
34+
</body>
35+
</html>

‎templates/manpage.html‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
<!DOCTYPE html>
2+
<html>
3+
<head>
4+
<meta charset="utf-8">
5+
<title>{{NAME}}(1) - uutils coreutils</title>
6+
<style>
7+
body { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif; max-width: 900px; margin: 0 auto; padding: 20px; line-height: 1.6; color: #333; }
8+
h1, h2 { color: #333; border-bottom: 1px solid #ddd; padding-bottom: 8px; }
9+
a { color: #007acc; text-decoration: none; }
10+
a:hover { text-decoration: underline; }
11+
pre, code { background: #f5f5f5; border-radius: 3px; }
12+
pre { padding: 12px; overflow-x: auto; border: 1px solid #ddd; }
13+
code { padding: 2px 5px; }
14+
dl dt { font-weight: bold; margin-top: 10px; }
15+
dl dd { margin-left: 20px; }
16+
.breadcrumb { margin-bottom: 20px; }
17+
.breadcrumb a { color: #007acc; }
18+
.manpage-content { margin-top: 20px; }
19+
.tldr-section { margin-top: 30px; padding: 20px; background: #f0f7ff; border: 1px solid #c0d8f0; border-radius: 8px; }
20+
.tldr-section h2 { color: #005a9e; border-bottom: 1px solid #c0d8f0; }
21+
.tldr-example { margin-bottom: 15px; }
22+
.tldr-desc { margin-bottom: 5px; font-style: italic; color: #555; }
23+
.tldr-example pre { background: #1e1e1e; color: #d4d4d4; border: none; }
24+
.top-bar { display: flex; justify-content: space-between; align-items: center; margin-bottom: 20px; }
25+
.top-links { display: flex; gap: 15px; font-size: 0.9em; }
26+
.top-links a { color: #007acc; }
27+
@media (prefers-color-scheme: dark) {
28+
body { background: #1a1a1a; color: #e0e0e0; }
29+
h1, h2 { color: #e0e0e0; border-bottom-color: #444; }
30+
pre, code { background: #2a2a2a; }
31+
pre { border-color: #444; }
32+
.tldr-section { background: #1a2a3a; border-color: #2a4a6a; }
33+
.tldr-section h2 { color: #6cb4ee; border-bottom-color: #2a4a6a; }
34+
.tldr-desc { color: #aaa; }
35+
}
36+
</style>
37+
</head>
38+
<body>
39+
<div class="top-bar">
40+
<div class="breadcrumb">
41+
<a href="/">Home</a> /
42+
<a href="/coreutils">Coreutils</a> /
43+
<a href="/coreutils/manpages/">Manual Pages</a> /
44+
<span>{{NAME}}(1)</span>
45+
</div>
46+
<div class="top-links">
47+
<a href="https://github.com/uutils/coreutils/tree/main/src/uu/{{NAME}}">Source code</a>
48+
<a href="https://github.com/uutils/coreutils/issues/new?title={{NAME}}:%20&labels=bug">Report an issue</a>
49+
</div>
50+
</div>
51+
<div class="manpage-content">
52+
{{CONTENT}}
53+
</div>
54+
{{TLDR}}
55+
</body>
56+
</html>

0 commit comments

Comments
 (0)