summaryrefslogtreecommitdiff
path: root/Documentation/user-manual.conf
AgeCommit message (Collapse)AuthorFilesLines
2020-03-31user-manual.conf: don't specify [listingblock]Libravatar Martin Ågren1-10/+0
This is the config file we use when we build the user manual with AsciiDoc. The comment at the top of this chunk that we're removing says the following: "unbreak" docbook-xsl v1.68 for manpages (sic!). v1.69 works with or without this. This comes from d19fbc3c17 ("Documentation: add git user's manual", 2007-01-07), where it looks like this conf file in general and this snippet in particular was copy-pasted from asciidoc.conf. This chunk is very similar to something we just got rid of for the manpages, and because this appears to be aimed at v1.68 -- which we no longer support for the manpages as of a few commits ago --, it's tempting to get rid of this. That reveals an interesting aspect of "works with or without this": it turns out it actually works /better/ without! Dropping this makes us render code snippets and shell listings using <screen> rather than <literallayout>, just like Asciidoctor does. In user-manual.pdf, this puts the contents into dimmed-background, easy-to-distinguish-from-the-surrounding-text boxes, as opposed to white-background (transparent) boxes. Signed-off-by: Martin Ågren <martin.agren@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2012-08-07docs: monospace listings in docbook outputLibravatar Jeff King1-1/+1
When asciidoc converts a listing block like: ---------------------- $ git log --merge ---------------------- it marks it to be displayed in a monospace font. This works fine when generating HTML output. However, when generating docbook output, we override the expansion of a listingblock to work around bugs in some versions of the docbook toolchain. Our override did not mark the listingblock with the "monospaced" class. The main output that uses docbook as an intermediate format is the manpages. We didn't notice any issue there because the monospaced class seems to be ignored when generating roff from the docbook manpages. However, when generating texinfo to make info pages, docbook does respect this class. The resulting texinfo output properly uses "@example" blocks to display the listing in this case. Besides possibly looking prettier in some texinfo backends, one important effect is that the monospace font suppresses texinfo's expansion of "--" and "---" into en-dashes and em-dashes. With the current code, the example above ends up looking like "git log -merge", which is confusing and wrong. Signed-off-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-01-06Documentation: rename gitlink macro to linkgitLibravatar Dan McGee1-1/+1
Between AsciiDoc 8.2.2 and 8.2.3, the following change was made to the stock Asciidoc configuration: @@ -149,7 +153,10 @@ # Inline macros. # Backslash prefix required for escape processing. # (?s) re flag for line spanning. -(?su)[\\]?(?P<name>\w(\w|-)*?):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + +# Explicit so they can be nested. +(?su)[\\]?(?P<name>(http|https|ftp|file|mailto|callto|image|link)):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + # Anchor: [[[id]]]. Bibliographic anchor. (?su)[\\]?\[\[\[(?P<attrlist>[\w][\w-]*?)\]\]\]=anchor3 # Anchor: [[id,xreflabel]] This default regex now matches explicit values, and unfortunately in this case gitlink was being matched by just 'link', causing the wrong inline macro template to be applied. By renaming the macro, we can avoid being matched by the wrong regex. Signed-off-by: Dan McGee <dpmcgee@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-01-07Documentation: add git user's manualLibravatar J. Bruce Fields1-0/+21
The goals are: - Readable from beginning to end in order without having read any other git documentation beforehand. - Helpful section names and cross-references, so it's not too hard to skip around some if you need to. - Organized to allow it to grow much larger (unlike the tutorials) It's more liesurely than tutorial.txt, but tries to stay focused on practical how-to stuff. It adds a discussion of how to resolve merge conflicts, and partial instructions on setting up and dealing with a public repository. I've lifted a little bit from "branching and merging" (e.g., some of the discussion of history diagrams), and could probably steal more if that's OK. (Similarly anyone should of course feel free to reuse bits of this if any parts seem more useful than the whole.) There's a lot of detail on managing branches and using git-fetch, just because those are essential even to people needing read-only access (e.g., kernel testers). I think those sections will be much shorter once the new "git remote" command and the disconnected checkouts are taken into account. I do feel bad about adding yet another piece of documentation, but I we need something that goes through all the basics in a logical order, and I wasn't seeing how to grow the tutorials into that. Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>