From: "Junio C Hamano" <gits...@pobox.com>
"Philip Oakley" <philipoak...@iee.org> writes:
I already have a local patch that creates a stalenote.txt file, and
includes that in a "release-notes(7)" man page, but it still leaves
the actual release notes in a separate plain text file, linked from
the man page, rather than being right at hand, which is what I think
readers would expect.
Sorry, but I still do not get it. If you have a script
Ah, no, it's not a script.
I had simply moved the content of the stalenotes section into its own
file 'stalenotes.txt' which could then be included both within the
git(1) section it came from, and a new release-notes(7) man page.
With that set up the Documentation/Makefile would generate the man
pages, with their appropriate links, which can be accessed via the 'git
help' command.
The big 'however' was that this would not actually include the latest
release notes as literal text for immediate reading into the
release-notes(7) man page, which would be my aim, and I think what
Stefan had suggested as a preferred style.
that reads
git.txt and extracts its stale-notes section to generate the source
to be processed into release-notes(7), why can't that script also
include the contents of the latest release notes inline into its
output?
My release notes are _not_ written to be compatible with/processable
by AsciiDoc (they are meant to be mere plain text)---perhaps you are
wondering if that would make it harder to maintain your script that
produces release-notes.txt?
Confused...
My thought was that the latest release note would be included as literal
text, as noted above.
Like you say, it may need to be a script, but I was being cautious about
what extra work that would entail for each release.
My other question would be to ask how you normally manage the
up-issue
of the stalenotes, and when you would normally create that section in
git(1) as I didn't see any ifdef::stalenotes[] being defined anywhere
else.
I'm not sure if I am understanding the question right (up-issue?),
but it used to be that the preformatted and web-reachable manual
pages at k.org were processed with stalenotes defined (which by the
way was disabled with adaa3caf "Meta/dodoc.sh: adjust to the new
layout, 2011-11-15" on the todo branch), and 26cfcfbf "Add release
notes to the distribution., 2007-02-13" used that facility to
prepare something like this:
I hadn't looked back into that part of history. I was somehow expecting
to see 'stalenotes' being defined somewhere in the current documenation
preparation options, hence my question about when you would set
'stalenotes'.
I'll have a look back at that to see how it was used back then.
docs/git.html
/git-cat-file.html
...
docs/vX.Y.Z/git.html
docs/vX.Y.Z/git-cat-file.html
...
where the "latest" one lived immediately underneath docs/*, while
older ones were in versioned subdirectories.
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
