Skip to content

Commit 1b4e9a5

Browse files
gitstergitster
committed
Merge branch 'ps/build-meson-html'
The build procedure based on meson learned to generate HTML documention pages. * ps/build-meson-html: Documentation: wire up sanity checks for Meson t/Makefile: make "check-meson" work with Dash meson: install static files for HTML documentation meson: generate articles Documentation: refactor "howto-index.sh" for out-of-tree builds Documentation: refactor "api-index.sh" for out-of-tree builds meson: generate user manual Documentation: inline user-manual.conf meson: generate HTML pages for all man page categories meson: fix generation of merge tools meson: properly wire up dependencies for our docs meson: wire up support for AsciiDoctor
2 parents effbef2 + 5419445 commit 1b4e9a5

File tree

12 files changed

+402
-63
lines changed

12 files changed

+402
-63
lines changed

‎Documentation/.gitignore

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@ cmds-*.txt
1212
mergetools-*.txt
1313
SubmittingPatches.txt
1414
tmp-doc-diff/
15+
tmp-meson-diff/
1516
GIT-ASCIIDOCFLAGS
1617
/.build/
1718
/GIT-EXCLUDED-PROGRAMS

‎Documentation/Makefile

Lines changed: 20 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -339,6 +339,7 @@ clean:
339339
$(RM) $(cmds_txt) $(mergetools_txt) *.made
340340
$(RM) GIT-ASCIIDOCFLAGS
341341
$(RM) asciidoc.conf asciidoctor-extensions.rb
342+
$(RM) -rf tmp-meson-diff
342343

343344
docinfo.html: docinfo-html.in
344345
$(QUIET_GEN)$(RM) $@ && cat $< >$@
@@ -362,12 +363,12 @@ manpage-cmd = $(QUIET_XMLTO)$(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $<
362363
%.xml : %.txt $(ASCIIDOC_DEPS)
363364
$(QUIET_ASCIIDOC)$(TXT_TO_XML) -d manpage -o $@ $<
364365

365-
user-manual.xml: user-manual.txt user-manual.conf $(ASCIIDOC_DEPS)
366+
user-manual.xml: user-manual.txt $(ASCIIDOC_DEPS)
366367
$(QUIET_ASCIIDOC)$(TXT_TO_XML) -d book -o $@ $<
367368

368369
technical/api-index.txt: technical/api-index-skel.txt \
369370
technical/api-index.sh $(patsubst %,%.txt,$(API_DOCS))
370-
$(QUIET_GEN)cd technical && '$(SHELL_PATH_SQ)' ./api-index.sh
371+
$(QUIET_GEN)'$(SHELL_PATH_SQ)' technical/api-index.sh ./technical ./technical/api-index.txt
371372

372373
technical/%.html: ASCIIDOC_EXTRA += -a git-relative-html-prefix=../
373374
$(patsubst %,%.html,$(API_DOCS) technical/api-index $(TECH_DOCS)): %.html : %.txt \
@@ -411,8 +412,8 @@ gitman.info: gitman.texi
411412
$(patsubst %.txt,%.texi,$(MAN_TXT)): %.texi : %.xml
412413
$(QUIET_DB2TEXI)$(DOCBOOK2X_TEXI) --to-stdout $*.xml >$@
413414

414-
howto-index.txt: howto-index.sh $(HOWTO_TXT)
415-
$(QUIET_GEN)'$(SHELL_PATH_SQ)' ./howto-index.sh $(sort $(HOWTO_TXT)) >$@
415+
howto-index.txt: howto/howto-index.sh $(HOWTO_TXT)
416+
$(QUIET_GEN)'$(SHELL_PATH_SQ)' ./howto/howto-index.sh $(sort $(HOWTO_TXT)) >$@
416417

417418
$(patsubst %,%.html,$(ARTICLES)) : %.html : %.txt $(ASCIIDOC_DEPS)
418419
$(QUIET_ASCIIDOC)$(TXT_TO_HTML) $*.txt
@@ -494,13 +495,28 @@ lint-docs-fsck-msgids: $(LINT_DOCS_FSCK_MSGIDS)
494495
lint-docs-manpages:
495496
$(QUIET_GEN)./lint-manpages.sh
496497

498+
.PHONY: lint-docs-meson
499+
lint-docs-meson:
500+
@# awk acts up when trying to match single quotes, so we use \047 instead.
501+
@mkdir -p tmp-meson-diff && \
502+
awk "/^manpages = {$$/ {flag=1 ; next } /^}$$/ { flag=0 } flag { gsub(/^ \047/, \"\"); gsub(/\047 : [157],\$$/, \"\"); print }" meson.build | \
503+
grep -v -e '#' -e '^$$' | \
504+
sort >tmp-meson-diff/meson.txt && \
505+
ls git*.txt scalar.txt | grep -v -e git-bisect-lk2009.txt -e git-tools.txt >tmp-meson-diff/actual.txt && \
506+
if ! cmp tmp-meson-diff/meson.txt tmp-meson-diff/actual.txt; then \
507+
echo "Meson man pages differ from actual man pages:"; \
508+
diff -u tmp-meson-diff/meson.txt tmp-meson-diff/actual.txt; \
509+
exit 1; \
510+
fi
511+
497512
## Lint: list of targets above
498513
.PHONY: lint-docs
499514
lint-docs: lint-docs-fsck-msgids
500515
lint-docs: lint-docs-gitlink
501516
lint-docs: lint-docs-man-end-blurb
502517
lint-docs: lint-docs-man-section-order
503518
lint-docs: lint-docs-manpages
519+
lint-docs: lint-docs-meson
504520

505521
ifeq ($(wildcard po/Makefile),po/Makefile)
506522
doc-l10n install-l10n::

‎Documentation/asciidoc.conf.in

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,12 +25,22 @@ manmanual=Git Manual
2525
mansource=Git @GIT_VERSION@
2626
revdate=@GIT_DATE@
2727

28+
ifdef::doctype-book[]
29+
[titles]
30+
underlines="__","==","--","~~","^^"
31+
endif::doctype-book[]
32+
2833
ifdef::backend-docbook[]
2934
[linkgit-inlinemacro]
35+
ifndef::doctype-book[]
3036
{0%{target}}
3137
{0#<citerefentry>}
3238
{0#<refentrytitle>{target}</refentrytitle><manvolnum>{0}</manvolnum>}
3339
{0#</citerefentry>}
40+
endif::doctype-book[]
41+
ifdef::doctype-book[]
42+
<ulink url="{target}.html">{target}{0?({0})}</ulink>
43+
endif::doctype-book[]
3444

3545
[literal-inlinemacro]
3646
{eval:re.sub(r'(&lt;[-a-zA-Z0-9.]+&gt;)', r'<emphasis>\1</emphasis>', re.sub(r'([\[\s|()>]|^|\]|&gt;)(\.?([-a-zA-Z0-9:+=~@,\/_^\$]+\.?)+)',r'\1<literal>\2</literal>', re.sub(r'(\.\.\.?)([^\]$.])', r'<literal>\1</literal>\2', macros.passthroughs[int(attrs['passtext'][1:-1])] if attrs['passtext'][1:-1].isnumeric() else attrs['passtext'][1:-1])))}

‎Documentation/howto-index.sh renamed to ‎Documentation/howto/howto-index.sh

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -48,7 +48,7 @@ do
4848
file="$txt"
4949
fi
5050

51-
echo "* link:$file[$title] $from
51+
echo "* link:howto/$(basename "$file")[$title] $from
5252
$abstract
5353
5454
"

‎Documentation/howto/meson.build

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
howto_sources = [
2+
'coordinate-embargoed-releases.txt',
3+
'keep-canonical-history-correct.txt',
4+
'maintain-git.txt',
5+
'new-command.txt',
6+
'rebase-from-internal-branch.txt',
7+
'rebuild-from-update-hook.txt',
8+
'recover-corrupted-blob-object.txt',
9+
'recover-corrupted-object-harder.txt',
10+
'revert-a-faulty-merge.txt',
11+
'revert-branch-rebase.txt',
12+
'separating-topic-branches.txt',
13+
'setup-git-server-over-http.txt',
14+
'update-hook-example.txt',
15+
'use-git-daemon.txt',
16+
'using-merge-subtree.txt',
17+
'using-signed-tag-in-pull-request.txt',
18+
]
19+
20+
howto_index = custom_target(
21+
command: [
22+
shell,
23+
meson.current_source_dir() / 'howto-index.sh',
24+
'@INPUT@',
25+
],
26+
env: script_environment,
27+
capture: true,
28+
input: howto_sources,
29+
output: 'howto-index.txt',
30+
)
31+
32+
custom_target(
33+
command: asciidoc_html_options,
34+
input: howto_index,
35+
output: 'howto-index.html',
36+
depends: documentation_deps,
37+
install: true,
38+
install_dir: get_option('datadir') / 'doc/git-doc',
39+
)
40+
41+
foreach howto : howto_sources
42+
howto_stripped = custom_target(
43+
command: [
44+
find_program('sed'),
45+
'-e',
46+
'1,/^$/d',
47+
'@INPUT@',
48+
],
49+
input: howto,
50+
output: fs.stem(howto) + '.stripped',
51+
capture: true,
52+
)
53+
54+
custom_target(
55+
command: asciidoc_html_options,
56+
input: howto_stripped,
57+
output: fs.stem(howto_stripped.full_path()) + '.html',
58+
depends: documentation_deps,
59+
install: true,
60+
install_dir: get_option('datadir') / 'doc/git-doc/howto',
61+
)
62+
endforeach

0 commit comments

Comments
 (0)