git/list[1] front-page[2] threads[3] people[4] search[5] about
 

Re: [PATCH] doc: substitute ETC_GIT(CONFIG|ATTRIBUTES) in generated docs

From
Todd Zullinger <tmz@pobox.com>
Date
Jun 27, 2018, 16:44 UTC
Message-ID
<20180627164443.GK20217@zaya.teonanacatl.net>
In-Reply-To
<20180627150352.GJ20217@zaya.teonanacatl.net>
I wrote:
Show 7 quoted lines
> Jeff King wrote:
>>      (Related, there's a build target in the local Makefile for using
>>      asciidoctor; does it need updated, too?)
> 
> I didn't test asciidoctor specficially, but it also respects
> the ASCIIDOC_EXTRA parameters, so I think it will work just
> as well.  I'll try to confirm that later today.

Testing confirmed that asciidoctor works fine with this as well.

Somewhat tangentially, I looked at using asciidoctor for the Fedora packages last year and one issue that kept me from using it then was the '[FIXME: source]' it includes in the footer of the manpage. When I dug into it at the time, it appeared this was due to no <refmiscinfo> declaration (similarly missing for manual, and version). It wasn't clear whether it was possible to include a custom header template in plain asciidoctor. I got the impression that it would require using a custom backend, which in turn required the rubygem 'tilt' for processing.

I spent about an hour poking around with it and decided that I'd put off building with asciidoctor until that was fixed. I felt that displaying '[FIXME: source]' wass worse than simply not including the version.

It's always possible that I was doing something wrong in my use of asciidoctor (I just set USE_ASCIIDOCTOR). Or maybe the Fedora packages are missing some dependency which I missed.

It might also be that we need some adjustments similar to https://patchwork.kernel.org/patch/10360207/ to get the mansource attribute passed on to asciidoctor. I only just ran across that patch and haven't had a chance to test sometime similar in the git manpage build. That looks promising though.

-- 
Todd
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Why is it that we rejoice at a birth and grieve at a funeral?  It is
because we are not the person involved.
    -- Mark Twain
Previous: Todd ZullingerNext: Jeff King
Message 4 of 11 in “doc: substitute ETC_GIT(CONFIG|ATTRIBUTES) in generated docs”
  1. doc: substitute ETC_GIT(CONFIG|ATTRIBUTES) in generated docsTodd Zullinger, Jun 27, 2018
  2. Jeff KingJun 27, 2018
  3. Todd ZullingerJun 27, 2018
  4. Todd ZullingerJun 27, 2018
  5. Jeff KingJun 28, 2018
  6. Jeff KingJun 28, 2018
  7. Todd ZullingerJun 28, 2018
  8. Jeff KingJun 28, 2018
  9. Junio C HamanoJun 27, 2018
  10. Todd ZullingerJun 27, 2018
  11. Jeff KingJun 28, 2018

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.