Skip to content

Commit 1f010d6

Browse files
bk2204gitster
authored andcommitted
doc: use .adoc extension for AsciiDoc files
We presently use the ".txt" extension for our AsciiDoc files. While not wrong, most editors do not associate this extension with AsciiDoc, meaning that contributors don't get automatic editor functionality that could be useful, such as syntax highlighting and prose linting. It is much more common to use the ".adoc" extension for AsciiDoc files, since this helps editors automatically detect files and also allows various forges to provide rich (HTML-like) rendering. Let's do that here, renaming all of the files and updating the includes where relevant. Adjust the various build scripts and makefiles to use the new extension as well. Note that this should not result in any user-visible changes to the documentation. Signed-off-by: brian m. carlson <[email protected]> Signed-off-by: Junio C Hamano <[email protected]>
1 parent ed4cf6e commit 1f010d6

File tree

919 files changed

+617
-617
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

919 files changed

+617
-617
lines changed

Documentation/Makefile

+100-100
Original file line numberDiff line numberDiff line change
@@ -17,56 +17,56 @@ OBSOLETE_HTML =
1717
-include GIT-EXCLUDED-PROGRAMS
1818

1919
MAN1_TXT += $(filter-out \
20-
$(patsubst %,%.txt,$(EXCLUDED_PROGRAMS)) \
21-
$(addsuffix .txt, $(ARTICLES) $(SP_ARTICLES)), \
22-
$(wildcard git-*.txt))
23-
MAN1_TXT += git.txt
24-
MAN1_TXT += gitk.txt
25-
MAN1_TXT += gitweb.txt
26-
MAN1_TXT += scalar.txt
20+
$(patsubst %,%.adoc,$(EXCLUDED_PROGRAMS)) \
21+
$(addsuffix .adoc, $(ARTICLES) $(SP_ARTICLES)), \
22+
$(wildcard git-*.adoc))
23+
MAN1_TXT += git.adoc
24+
MAN1_TXT += gitk.adoc
25+
MAN1_TXT += gitweb.adoc
26+
MAN1_TXT += scalar.adoc
2727

2828
# man5 / man7 guides (note: new guides should also be added to command-list.txt)
29-
MAN5_TXT += gitattributes.txt
30-
MAN5_TXT += gitformat-bundle.txt
31-
MAN5_TXT += gitformat-chunk.txt
32-
MAN5_TXT += gitformat-commit-graph.txt
33-
MAN5_TXT += gitformat-index.txt
34-
MAN5_TXT += gitformat-pack.txt
35-
MAN5_TXT += gitformat-signature.txt
36-
MAN5_TXT += githooks.txt
37-
MAN5_TXT += gitignore.txt
38-
MAN5_TXT += gitmailmap.txt
39-
MAN5_TXT += gitmodules.txt
40-
MAN5_TXT += gitprotocol-capabilities.txt
41-
MAN5_TXT += gitprotocol-common.txt
42-
MAN5_TXT += gitprotocol-http.txt
43-
MAN5_TXT += gitprotocol-pack.txt
44-
MAN5_TXT += gitprotocol-v2.txt
45-
MAN5_TXT += gitrepository-layout.txt
46-
MAN5_TXT += gitweb.conf.txt
47-
48-
MAN7_TXT += gitcli.txt
49-
MAN7_TXT += gitcore-tutorial.txt
50-
MAN7_TXT += gitcredentials.txt
51-
MAN7_TXT += gitcvs-migration.txt
52-
MAN7_TXT += gitdiffcore.txt
53-
MAN7_TXT += giteveryday.txt
54-
MAN7_TXT += gitfaq.txt
55-
MAN7_TXT += gitglossary.txt
56-
MAN7_TXT += gitpacking.txt
57-
MAN7_TXT += gitnamespaces.txt
58-
MAN7_TXT += gitremote-helpers.txt
59-
MAN7_TXT += gitrevisions.txt
60-
MAN7_TXT += gitsubmodules.txt
61-
MAN7_TXT += gittutorial-2.txt
62-
MAN7_TXT += gittutorial.txt
63-
MAN7_TXT += gitworkflows.txt
64-
65-
HOWTO_TXT += $(wildcard howto/*.txt)
66-
67-
DOC_DEP_TXT += $(wildcard *.txt)
68-
DOC_DEP_TXT += $(wildcard config/*.txt)
69-
DOC_DEP_TXT += $(wildcard includes/*.txt)
29+
MAN5_TXT += gitattributes.adoc
30+
MAN5_TXT += gitformat-bundle.adoc
31+
MAN5_TXT += gitformat-chunk.adoc
32+
MAN5_TXT += gitformat-commit-graph.adoc
33+
MAN5_TXT += gitformat-index.adoc
34+
MAN5_TXT += gitformat-pack.adoc
35+
MAN5_TXT += gitformat-signature.adoc
36+
MAN5_TXT += githooks.adoc
37+
MAN5_TXT += gitignore.adoc
38+
MAN5_TXT += gitmailmap.adoc
39+
MAN5_TXT += gitmodules.adoc
40+
MAN5_TXT += gitprotocol-capabilities.adoc
41+
MAN5_TXT += gitprotocol-common.adoc
42+
MAN5_TXT += gitprotocol-http.adoc
43+
MAN5_TXT += gitprotocol-pack.adoc
44+
MAN5_TXT += gitprotocol-v2.adoc
45+
MAN5_TXT += gitrepository-layout.adoc
46+
MAN5_TXT += gitweb.conf.adoc
47+
48+
MAN7_TXT += gitcli.adoc
49+
MAN7_TXT += gitcore-tutorial.adoc
50+
MAN7_TXT += gitcredentials.adoc
51+
MAN7_TXT += gitcvs-migration.adoc
52+
MAN7_TXT += gitdiffcore.adoc
53+
MAN7_TXT += giteveryday.adoc
54+
MAN7_TXT += gitfaq.adoc
55+
MAN7_TXT += gitglossary.adoc
56+
MAN7_TXT += gitpacking.adoc
57+
MAN7_TXT += gitnamespaces.adoc
58+
MAN7_TXT += gitremote-helpers.adoc
59+
MAN7_TXT += gitrevisions.adoc
60+
MAN7_TXT += gitsubmodules.adoc
61+
MAN7_TXT += gittutorial-2.adoc
62+
MAN7_TXT += gittutorial.adoc
63+
MAN7_TXT += gitworkflows.adoc
64+
65+
HOWTO_TXT += $(wildcard howto/*.adoc)
66+
67+
DOC_DEP_TXT += $(wildcard *.adoc)
68+
DOC_DEP_TXT += $(wildcard config/*.adoc)
69+
DOC_DEP_TXT += $(wildcard includes/*.adoc)
7070

7171
ifdef MAN_FILTER
7272
MAN_TXT = $(filter $(MAN_FILTER),$(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT))
@@ -75,8 +75,8 @@ MAN_TXT = $(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT)
7575
MAN_FILTER = $(MAN_TXT)
7676
endif
7777

78-
MAN_XML = $(patsubst %.txt,%.xml,$(MAN_TXT))
79-
MAN_HTML = $(patsubst %.txt,%.html,$(MAN_TXT))
78+
MAN_XML = $(patsubst %.adoc,%.xml,$(MAN_TXT))
79+
MAN_HTML = $(patsubst %.adoc,%.html,$(MAN_TXT))
8080
GIT_MAN_REF = master
8181

8282
OBSOLETE_HTML += everyday.html
@@ -103,7 +103,7 @@ SP_ARTICLES += howto/rebase-from-internal-branch
103103
SP_ARTICLES += howto/keep-canonical-history-correct
104104
SP_ARTICLES += howto/maintain-git
105105
SP_ARTICLES += howto/coordinate-embargoed-releases
106-
API_DOCS = $(patsubst %.txt,%,$(filter-out technical/api-index-skel.txt technical/api-index.txt, $(wildcard technical/api-*.txt)))
106+
API_DOCS = $(patsubst %.adoc,%,$(filter-out technical/api-index-skel.adoc technical/api-index.adoc, $(wildcard technical/api-*.adoc)))
107107
SP_ARTICLES += $(API_DOCS)
108108

109109
TECH_DOCS += DecisionMaking
@@ -136,9 +136,9 @@ ARTICLES_HTML += $(patsubst %,%.html,$(ARTICLES) $(SP_ARTICLES))
136136
HTML_FILTER ?= $(ARTICLES_HTML) $(OBSOLETE_HTML)
137137
DOC_HTML = $(MAN_HTML) $(filter $(HTML_FILTER),$(ARTICLES_HTML) $(OBSOLETE_HTML))
138138

139-
DOC_MAN1 = $(patsubst %.txt,%.1,$(filter $(MAN_FILTER),$(MAN1_TXT)))
140-
DOC_MAN5 = $(patsubst %.txt,%.5,$(filter $(MAN_FILTER),$(MAN5_TXT)))
141-
DOC_MAN7 = $(patsubst %.txt,%.7,$(filter $(MAN_FILTER),$(MAN7_TXT)))
139+
DOC_MAN1 = $(patsubst %.adoc,%.1,$(filter $(MAN_FILTER),$(MAN1_TXT)))
140+
DOC_MAN5 = $(patsubst %.adoc,%.5,$(filter $(MAN_FILTER),$(MAN5_TXT)))
141+
DOC_MAN7 = $(patsubst %.adoc,%.7,$(filter $(MAN_FILTER),$(MAN7_TXT)))
142142

143143
prefix ?= $(HOME)
144144
bindir ?= $(prefix)/bin
@@ -278,7 +278,7 @@ install-pdf: pdf
278278
install-html: html
279279
'$(SHELL_PATH_SQ)' ./install-webdoc.sh $(DESTDIR)$(htmldir)
280280

281-
mergetools_txt = mergetools-diff.txt mergetools-merge.txt
281+
mergetools_txt = mergetools-diff.adoc mergetools-merge.adoc
282282

283283
#
284284
# Determine "include::" file references in asciidoc files.
@@ -294,29 +294,29 @@ ifneq ($(MAKECMDGOALS),clean)
294294
-include doc.dep
295295
endif
296296

297-
cmds_txt = cmds-ancillaryinterrogators.txt \
298-
cmds-ancillarymanipulators.txt \
299-
cmds-mainporcelain.txt \
300-
cmds-plumbinginterrogators.txt \
301-
cmds-plumbingmanipulators.txt \
302-
cmds-synchingrepositories.txt \
303-
cmds-synchelpers.txt \
304-
cmds-guide.txt \
305-
cmds-developerinterfaces.txt \
306-
cmds-userinterfaces.txt \
307-
cmds-purehelpers.txt \
308-
cmds-foreignscminterface.txt
297+
cmds_txt = cmds-ancillaryinterrogators.adoc \
298+
cmds-ancillarymanipulators.adoc \
299+
cmds-mainporcelain.adoc \
300+
cmds-plumbinginterrogators.adoc \
301+
cmds-plumbingmanipulators.adoc \
302+
cmds-synchingrepositories.adoc \
303+
cmds-synchelpers.adoc \
304+
cmds-guide.adoc \
305+
cmds-developerinterfaces.adoc \
306+
cmds-userinterfaces.adoc \
307+
cmds-purehelpers.adoc \
308+
cmds-foreignscminterface.adoc
309309

310310
$(cmds_txt): cmd-list.made
311311

312312
cmd-list.made: cmd-list.perl ../command-list.txt $(MAN1_TXT)
313313
$(QUIET_GEN)$(PERL_PATH) ./cmd-list.perl .. . $(cmds_txt) && \
314314
date >$@
315315

316-
mergetools-%.txt: generate-mergetool-list.sh ../git-mergetool--lib.sh $(wildcard ../mergetools/*)
317-
mergetools-diff.txt:
316+
mergetools-%.adoc: generate-mergetool-list.sh ../git-mergetool--lib.sh $(wildcard ../mergetools/*)
317+
mergetools-diff.adoc:
318318
$(QUIET_GEN)$(SHELL_PATH) ./generate-mergetool-list.sh .. diff $@
319-
mergetools-merge.txt:
319+
mergetools-merge.adoc:
320320
$(QUIET_GEN)$(SHELL_PATH) ./generate-mergetool-list.sh .. merge $@
321321

322322
TRACK_ASCIIDOCFLAGS = $(subst ','\'',$(ASCIIDOC_COMMON):$(ASCIIDOC_HTML):$(ASCIIDOC_DOCBOOK))
@@ -333,9 +333,9 @@ clean:
333333
$(RM) *.xml *.xml+ *.html *.html+ *.1 *.5 *.7
334334
$(RM) *.texi *.texi+ *.texi++ git.info gitman.info
335335
$(RM) *.pdf
336-
$(RM) howto-index.txt howto/*.html doc.dep
337-
$(RM) technical/*.html technical/api-index.txt
338-
$(RM) SubmittingPatches.txt
336+
$(RM) howto-index.adoc howto/*.html doc.dep
337+
$(RM) technical/*.html technical/api-index.adoc
338+
$(RM) SubmittingPatches.adoc
339339
$(RM) $(cmds_txt) $(mergetools_txt) *.made
340340
$(RM) GIT-ASCIIDOCFLAGS
341341
$(RM) asciidoc.conf asciidoctor-extensions.rb
@@ -344,10 +344,10 @@ clean:
344344
docinfo.html: docinfo-html.in
345345
$(QUIET_GEN)$(RM) $@ && cat $< >$@
346346

347-
$(MAN_HTML): %.html : %.txt $(ASCIIDOC_DEPS)
347+
$(MAN_HTML): %.html : %.adoc $(ASCIIDOC_DEPS)
348348
$(QUIET_ASCIIDOC)$(TXT_TO_HTML) -d manpage -o $@ $<
349349

350-
$(OBSOLETE_HTML): %.html : %.txto $(ASCIIDOC_DEPS)
350+
$(OBSOLETE_HTML): %.html : %.adoco $(ASCIIDOC_DEPS)
351351
$(QUIET_ASCIIDOC)$(TXT_TO_HTML) -o $@ $<
352352

353353
manpage-prereqs := $(wildcard manpage*.xsl)
@@ -360,22 +360,22 @@ manpage-cmd = $(QUIET_XMLTO)$(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $<
360360
%.7 : %.xml $(manpage-prereqs)
361361
$(manpage-cmd)
362362

363-
%.xml : %.txt $(ASCIIDOC_DEPS)
363+
%.xml : %.adoc $(ASCIIDOC_DEPS)
364364
$(QUIET_ASCIIDOC)$(TXT_TO_XML) -d manpage -o $@ $<
365365

366-
user-manual.xml: user-manual.txt $(ASCIIDOC_DEPS)
366+
user-manual.xml: user-manual.adoc $(ASCIIDOC_DEPS)
367367
$(QUIET_ASCIIDOC)$(TXT_TO_XML) -d book -o $@ $<
368368

369-
technical/api-index.txt: technical/api-index-skel.txt \
370-
technical/api-index.sh $(patsubst %,%.txt,$(API_DOCS))
371-
$(QUIET_GEN)'$(SHELL_PATH_SQ)' technical/api-index.sh ./technical ./technical/api-index.txt
369+
technical/api-index.adoc: technical/api-index-skel.adoc \
370+
technical/api-index.sh $(patsubst %,%.adoc,$(API_DOCS))
371+
$(QUIET_GEN)'$(SHELL_PATH_SQ)' technical/api-index.sh ./technical ./technical/api-index.adoc
372372

373373
technical/%.html: ASCIIDOC_EXTRA += -a git-relative-html-prefix=../
374-
$(patsubst %,%.html,$(API_DOCS) technical/api-index $(TECH_DOCS)): %.html : %.txt \
374+
$(patsubst %,%.html,$(API_DOCS) technical/api-index $(TECH_DOCS)): %.html : %.adoc \
375375
$(ASCIIDOC_DEPS)
376-
$(QUIET_ASCIIDOC)$(TXT_TO_HTML) $*.txt
376+
$(QUIET_ASCIIDOC)$(TXT_TO_HTML) $*.adoc
377377

378-
SubmittingPatches.txt: SubmittingPatches
378+
SubmittingPatches.adoc: SubmittingPatches
379379
$(QUIET_GEN) cp $< $@
380380

381381
XSLT = docbook.xsl
@@ -409,19 +409,19 @@ gitman.texi: $(MAN_XML) cat-texi.perl texi.xsl
409409
gitman.info: gitman.texi
410410
$(QUIET_MAKEINFO)$(MAKEINFO) --no-split --no-validate $<
411411

412-
$(patsubst %.txt,%.texi,$(MAN_TXT)): %.texi : %.xml
412+
$(patsubst %.adoc,%.texi,$(MAN_TXT)): %.texi : %.xml
413413
$(QUIET_DB2TEXI)$(DOCBOOK2X_TEXI) --to-stdout $*.xml >$@
414414

415-
howto-index.txt: howto/howto-index.sh $(HOWTO_TXT)
415+
howto-index.adoc: howto/howto-index.sh $(HOWTO_TXT)
416416
$(QUIET_GEN)'$(SHELL_PATH_SQ)' ./howto/howto-index.sh $(sort $(HOWTO_TXT)) >$@
417417

418-
$(patsubst %,%.html,$(ARTICLES)) : %.html : %.txt $(ASCIIDOC_DEPS)
419-
$(QUIET_ASCIIDOC)$(TXT_TO_HTML) $*.txt
418+
$(patsubst %,%.html,$(ARTICLES)) : %.html : %.adoc $(ASCIIDOC_DEPS)
419+
$(QUIET_ASCIIDOC)$(TXT_TO_HTML) $*.adoc
420420

421421
WEBDOC_DEST = /pub/software/scm/git/docs
422422

423423
howto/%.html: ASCIIDOC_EXTRA += -a git-relative-html-prefix=../
424-
$(patsubst %.txt,%.html,$(HOWTO_TXT)): %.html : %.txt $(ASCIIDOC_DEPS)
424+
$(patsubst %.adoc,%.html,$(HOWTO_TXT)): %.html : %.adoc $(ASCIIDOC_DEPS)
425425
$(QUIET_ASCIIDOC) \
426426
sed -e '1,/^$$/d' $< | \
427427
$(TXT_TO_HTML) - >$@
@@ -452,9 +452,9 @@ print-man1:
452452
@for i in $(MAN1_TXT); do echo $$i; done
453453

454454
## Lint: gitlink
455-
LINT_DOCS_GITLINK = $(patsubst %.txt,.build/lint-docs/gitlink/%.ok,$(HOWTO_TXT) $(DOC_DEP_TXT))
455+
LINT_DOCS_GITLINK = $(patsubst %.adoc,.build/lint-docs/gitlink/%.ok,$(HOWTO_TXT) $(DOC_DEP_TXT))
456456
$(LINT_DOCS_GITLINK): lint-gitlink.perl
457-
$(LINT_DOCS_GITLINK): .build/lint-docs/gitlink/%.ok: %.txt
457+
$(LINT_DOCS_GITLINK): .build/lint-docs/gitlink/%.ok: %.adoc
458458
$(call mkdir_p_parent_template)
459459
$(QUIET_LINT_GITLINK)$(PERL_PATH) lint-gitlink.perl \
460460
$< \
@@ -466,17 +466,17 @@ $(LINT_DOCS_GITLINK): .build/lint-docs/gitlink/%.ok: %.txt
466466
lint-docs-gitlink: $(LINT_DOCS_GITLINK)
467467

468468
## Lint: man-end-blurb
469-
LINT_DOCS_MAN_END_BLURB = $(patsubst %.txt,.build/lint-docs/man-end-blurb/%.ok,$(MAN_TXT))
469+
LINT_DOCS_MAN_END_BLURB = $(patsubst %.adoc,.build/lint-docs/man-end-blurb/%.ok,$(MAN_TXT))
470470
$(LINT_DOCS_MAN_END_BLURB): lint-man-end-blurb.perl
471-
$(LINT_DOCS_MAN_END_BLURB): .build/lint-docs/man-end-blurb/%.ok: %.txt
471+
$(LINT_DOCS_MAN_END_BLURB): .build/lint-docs/man-end-blurb/%.ok: %.adoc
472472
$(call mkdir_p_parent_template)
473473
$(QUIET_LINT_MANEND)$(PERL_PATH) lint-man-end-blurb.perl $< >$@
474474
.PHONY: lint-docs-man-end-blurb
475475

476476
## Lint: man-section-order
477-
LINT_DOCS_MAN_SECTION_ORDER = $(patsubst %.txt,.build/lint-docs/man-section-order/%.ok,$(MAN_TXT))
477+
LINT_DOCS_MAN_SECTION_ORDER = $(patsubst %.adoc,.build/lint-docs/man-section-order/%.ok,$(MAN_TXT))
478478
$(LINT_DOCS_MAN_SECTION_ORDER): lint-man-section-order.perl
479-
$(LINT_DOCS_MAN_SECTION_ORDER): .build/lint-docs/man-section-order/%.ok: %.txt
479+
$(LINT_DOCS_MAN_SECTION_ORDER): .build/lint-docs/man-section-order/%.ok: %.adoc
480480
$(call mkdir_p_parent_template)
481481
$(QUIET_LINT_MANSEC)$(PERL_PATH) lint-man-section-order.perl $< >$@
482482
.PHONY: lint-docs-man-section-order
@@ -485,10 +485,10 @@ lint-docs-man-section-order: $(LINT_DOCS_MAN_SECTION_ORDER)
485485
.PHONY: lint-docs-fsck-msgids
486486
LINT_DOCS_FSCK_MSGIDS = .build/lint-docs/fsck-msgids.ok
487487
$(LINT_DOCS_FSCK_MSGIDS): lint-fsck-msgids.perl
488-
$(LINT_DOCS_FSCK_MSGIDS): ../fsck.h fsck-msgids.txt
488+
$(LINT_DOCS_FSCK_MSGIDS): ../fsck.h fsck-msgids.adoc
489489
$(call mkdir_p_parent_template)
490490
$(QUIET_GEN)$(PERL_PATH) lint-fsck-msgids.perl \
491-
../fsck.h fsck-msgids.txt $@
491+
../fsck.h fsck-msgids.adoc $@
492492

493493
lint-docs-fsck-msgids: $(LINT_DOCS_FSCK_MSGIDS)
494494

@@ -501,11 +501,11 @@ lint-docs-meson:
501501
@mkdir -p tmp-meson-diff && \
502502
awk "/^manpages = {$$/ {flag=1 ; next } /^}$$/ { flag=0 } flag { gsub(/^ \047/, \"\"); gsub(/\047 : [157],\$$/, \"\"); print }" meson.build | \
503503
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 \
504+
sort >tmp-meson-diff/meson.adoc && \
505+
ls git*.adoc scalar.adoc | grep -v -e git-bisect-lk2009.adoc -e git-tools.adoc >tmp-meson-diff/actual.adoc && \
506+
if ! cmp tmp-meson-diff/meson.adoc tmp-meson-diff/actual.adoc; then \
507507
echo "Meson man pages differ from actual man pages:"; \
508-
diff -u tmp-meson-diff/meson.txt tmp-meson-diff/actual.txt; \
508+
diff -u tmp-meson-diff/meson.adoc tmp-meson-diff/actual.adoc; \
509509
exit 1; \
510510
fi
511511

0 commit comments

Comments
 (0)