The requirement for a 'SYNOPSIS' section in section 7 manual pages
has been relaxed by updating the linter script, and dummy
'SYNOPSIS' sections from existing section 7 documentation have been
removed to improve the rendered output
* je/doc-section-7-synopsis:
doc: don't require a SYNOPSIS in section 7
Remove the SYNOPSIS section from the section 7 man pages where
appropriate, to avoid having a section that contains no information.
It's not the norm in section 7 to always require a SYNOPSIS.
Update the perl script with a special case for section 7.
Tested by running `make lint-docs`, and looked at the renaming synopses
with this fish script snippet:
for i in *.7
echo $i; grep SYNOPSIS -A 5 (string replace .7 .adoc $i)
end
Co-authored-by: Tuomas Ahola <taahol@utu.fi>
Signed-off-by: Tuomas Ahola <taahol@utu.fi>
Signed-off-by: Julia Evans <julia@jvns.ca>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Instead of saying "see EXAMPLES below", say "see <<EXAMPLES,EXAMPLES>>
below" to make the man pages easier to navigate on the web.
The reason for using the more verbose <<EXAMPLES,EXAMPLES>>
(instead of <<EXAMPLES>>) is that in some cases, <<EXAMPLES>> is
rendered as `the section called "EXAMPLES"` or `[EXAMPLES]`.
<<EXAMPLES,EXAMPLES>> is rendered as `EXAMPLES`, which gives us more
control over the output.
This also changes some of the HTML IDs of the headings from `_examples`
to `EXAMPLES`, which has the potential to break some links.
Signed-off-by: Julia Evans <julia@jvns.ca>
Acked-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
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 <sandals@crustytoothpaste.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Junio C Hamano