From 760a7cfc29f0645056b04e4d6f7c63cb46b4d384 Mon Sep 17 00:00:00 2001 From: =?utf8?q?Karl=20Hasselstr=C3=B6m?= Date: Fri, 13 Mar 2009 04:14:42 +0100 Subject: [PATCH] Documentation: Rename link macros MIME-Version: 1.0 Content-Type: text/plain; charset=utf8 Content-Transfer-Encoding: 8bit They can no longer end with "link", as explained in commit 5162e697 by Dan McGee in the git repository: Documentation: rename gitlink macro to linkgit 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\w(\w|-)*?):(?P\S*?)(\[(?P.*?)\])= + +# Explicit so they can be nested. +(?su)[\\]?(?P(http|https|ftp|file|mailto|callto|image|link)):(?P\S*?)(\[(?P.*?)\])= + # Anchor: [[[id]]]. Bibliographic anchor. (?su)[\\]?\[\[\[(?P[\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: Karl Hasselström --- Documentation/asciidoc.conf | 19 ++++---- Documentation/stg.txt | 10 ++-- Documentation/tutorial.txt | 116 ++++++++++++++++++++++---------------------- stgit/commands/__init__.py | 2 +- stgit/commands/branch.py | 6 +-- stgit/commands/clone.py | 6 +-- stgit/commands/new.py | 2 +- stgit/commands/sink.py | 2 +- 8 files changed, 81 insertions(+), 82 deletions(-) diff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf index f2c0ede..d40b4a8 100644 --- a/Documentation/asciidoc.conf +++ b/Documentation/asciidoc.conf @@ -80,38 +80,37 @@ ifdef::backend-xhtml11[] {target}{0?({0})} endif::backend-xhtml11[] -## stglink: macro +## linkstg: macro # -# Usage: stglink:command[] +# Usage: linkstg:command[] # # Show StGit link as: stg-(1) in man pages, stg in # html. ifdef::backend-docbook[] -[stglink-inlinemacro] +[linkstg-inlinemacro] stg-{target}1 endif::backend-docbook[] ifdef::backend-xhtml11[] -[stglink-inlinemacro] +[linkstg-inlinemacro] stg {target} endif::backend-xhtml11[] -## stgsublink: macro +## linkstgsub: macro # -# Usage: stgsublink:command[] +# Usage: linkstgsub:command[] # -# Show StGit link as: in man pages, stg in -# html. +# Show StGit link as: . ifdef::backend-docbook[] -[stgsublink-inlinemacro] +[linkstgsub-inlinemacro] {target} endif::backend-docbook[] ifdef::backend-xhtml11[] -[stgsublink-inlinemacro] +[linkstgsub-inlinemacro] {target} endif::backend-xhtml11[] diff --git a/Documentation/stg.txt b/Documentation/stg.txt index fc8fd7c..4cdff53 100644 --- a/Documentation/stg.txt +++ b/Documentation/stg.txt @@ -63,8 +63,8 @@ Tracking branch:: final sequence of patches, and not the messy sequence of edits that produced them. + -Commands of interest in this workflow are e.g. stgsublink:rebase[] and -stgsublink:mail[]. +Commands of interest in this workflow are e.g. linkstgsub:rebase[] and +linkstgsub:mail[]. Development branch:: @@ -77,10 +77,10 @@ Development branch:: immortalized every misstep you made on your way to the right solution. + -Commands of interest in this workflow are e.g. stgsublink:uncommit[], +Commands of interest in this workflow are e.g. linkstgsub:uncommit[], which can be used to move the patch stack base downwards -- i.e., turn Git commits into StGit patches after the fact -- and -stgsublink:commit[], its inverse. +linkstgsub:commit[], its inverse. For more information, see htmllink:tutorial.html[the tutorial]. @@ -111,7 +111,7 @@ stack base (the commit just below the bottommost patch); so, +abranch:$${base}$$+ is the base of the stack in branch +abranch+. If you need to pass a given StGit reference to a Git command, -stglink:id[] will convert it to a Git commit id for you. +linkstg:id[] will convert it to a Git commit id for you. OPTIONS ------- diff --git a/Documentation/tutorial.txt b/Documentation/tutorial.txt index 44435f0..8e0adbf 100644 --- a/Documentation/tutorial.txt +++ b/Documentation/tutorial.txt @@ -43,7 +43,7 @@ one of those; if you don't have one at hand, try for example $ git clone http://homepage.ntlworld.com/cmarinas/stgit.git $ cd stgit -Before you can create StGit patches, you have to run stglink:init[]: +Before you can create StGit patches, you have to run linkstg:init[]: $ stg init @@ -51,7 +51,7 @@ This initializes the StGit metadata for the current branch. (So if you want to have StGit patches in another branch too, you need to run +stg init+ again in that branch.) -NOTE: As a shortcut, stglink:clone[] will run +git clone+ followed by +NOTE: As a shortcut, linkstg:clone[] will run +git clone+ followed by +stg init+ for you. @@ -65,7 +65,7 @@ Now we're ready to create our first patch: This will create a patch called +my-first-patch+, and open an editor to let you edit the patch's commit message. (If you don't give a name on the command line, StGit will make one up based on the first line of -the commit message.) This patch is empty, as stglink:show[] will tell +the commit message.) This patch is empty, as linkstg:show[] will tell you: $ stg show @@ -77,7 +77,7 @@ local changes in your tree: $ stg status M stgit/main.py -Then stgsublink:refresh[] the patch: +Then linkstgsub:refresh[] the patch: $ stg refresh @@ -123,7 +123,7 @@ it: $ stg refresh Note that we can give the commit message on the command line, and that -it doesn't matter whether we run stglink:new[] before or after we edit +it doesn't matter whether we run linkstg:new[] before or after we edit the files. So now we have two patches: @@ -132,13 +132,13 @@ So now we have two patches: + my-first-patch # This is my first patch > credit # Give me some credit -stglink:series[] lists the patches from bottom to top; +$$+$$+ means +linkstg:series[] lists the patches from bottom to top; +$$+$$+ means that a patch is 'applied', and +>+ that it is the 'current', or topmost, patch. If we want to make further changes to the topmost patch, we just edit the files and run +stg refresh+. But what if we wanted to change -+my-first-patch+? The simplest way is to stgsublink:pop[] the +credit+ ++my-first-patch+? The simplest way is to linkstgsub:pop[] the +credit+ patch, so that +my-first-patch+ becomes topmost again: $ stg pop credit @@ -149,15 +149,15 @@ patch, so that +my-first-patch+ becomes topmost again: > my-first-patch # This is my first patch - credit # Give me some credit -stglink:series[] now shows that +my-first-patch+ is topmost again, -which means that stglink:refresh[] will update it with any changes we +linkstg:series[] now shows that +my-first-patch+ is topmost again, +which means that linkstg:refresh[] will update it with any changes we make. The minus sign says that +credit+ is 'unapplied' -- this means that it's been temporarily put aside. If you look at the +AUTHORS+ file, you'll see that our change to it is gone; and tools such as manlink:gitk[] will not show it, because it's been edited out of the -Git history. But it's just one stglink:push[] command away from being +Git history. But it's just one linkstg:push[] command away from being restored: $ stg push credit @@ -165,14 +165,14 @@ restored: Fast-forwarded patch "credit" Now at patch "credit" -NOTE: You can omit the patch name argument to stglink:push[] and -stglink:pop[]. If you do, you will push the next unapplied patch, and +NOTE: You can omit the patch name argument to linkstg:push[] and +linkstg:pop[]. If you do, you will push the next unapplied patch, and pop the topmost patch, respectively. NOTE: There are at least two more ways to update a non-topmost patch. -One is to use stglink:refresh[] with the +$$--patch$$+ flag, the other +One is to use linkstg:refresh[] with the +$$--patch$$+ flag, the other to create a new patch for the update and then merge it into the other -patch with stglink:squash[]. +patch with linkstg:squash[]. Keeping commit messages up to date @@ -181,19 +181,19 @@ Keeping commit messages up to date Since StGit is all about creating readable Git history (or a readable patch series, which is essentially the same thing), one thing you'll want to pay attention to is the commit messages of your patches. -stglink:new[] asks you for a commit message when you create a new +linkstg:new[] asks you for a commit message when you create a new patch, but as time goes by and you refresh the patch again and again, chances are that the original commit message isn't quite correct anymore. Fortunately, editing the commit message is very easy: $ stg edit -In addition to stglink:edit[], you can also give the +$$--edit$$+ flag -to stglink:refresh[] -- that way, you get to change the commit message +In addition to linkstg:edit[], you can also give the +$$--edit$$+ flag +to linkstg:refresh[] -- that way, you get to change the commit message and update the patch at the same time. Use whichever feels most natural to you. -NOTE: stglink:edit[] has a +$$--diff$$+ flag, which gives you the diff +NOTE: linkstg:edit[] has a +$$--diff$$+ flag, which gives you the diff text and not just the commit message in your editor. Be aware, though, that if you change the diff so that it no longer applies, the edit will be saved to a file instead of being carried out. If you're not @@ -201,7 +201,7 @@ comfortable editing diffs, just treat +$$--diff$$+ as a way to get to 'see' the diff while you edit the commit message. If the patch changes considerably, it might even deserve a new name. -stglink:rename[] is your friend there. +linkstg:rename[] is your friend there. Conflicts @@ -255,7 +255,7 @@ when we try to have them both applied? StGit is telling us that it couldn't figure out how to push +first+ on top of +second+, now that they both modify +TODO+. We can take a look -at the situation with stglink:status[]: +at the situation with linkstg:status[]: $ stg status ? TODO.ancestor @@ -263,7 +263,7 @@ at the situation with stglink:status[]: ? TODO.patched C TODO -As we were told by stglink:push[], the conflict is in the file +TODO+. +As we were told by linkstg:push[], the conflict is in the file +TODO+. (If the patch was bigger and touched multiple files, they would all be listed here; prefixed with +C+ if they had conflicts, and +M+ if StGit managed to automatically resolve everything in the file.) @@ -276,7 +276,7 @@ that contains neither of the added lines. At this point, we have two options: - 1. Undo the failed merge with stglink:undo[]. (Remember to use the + 1. Undo the failed merge with linkstg:undo[]. (Remember to use the +$$--hard$$+ flag, since the unresolved conflict means the worktree is not clean.) @@ -387,26 +387,26 @@ commits: + fix-documentation-error # Fix documentation error > more-snarfle-cache # More snarfle cache -As you can see, stglink:uncommit[] adds StGit metadata to the last few +As you can see, linkstg:uncommit[] adds StGit metadata to the last few Git commits, turning them into StGit patches so that we can do stuff with them. -NOTE: With the +$$--number$$+ flag, stglink:uncommit[] uncommits that +NOTE: With the +$$--number$$+ flag, linkstg:uncommit[] uncommits that many commits and generates names for them based on their commit messages. If you like, you can instead list the patch names you want on the command line. At this point, there are a number of things we could do: - * Continue developing, and take advantage of e.g. stglink:goto[] or + * Continue developing, and take advantage of e.g. linkstg:goto[] or +stg refresh $$--patch$$+ to stick updates in the right patch to begin with. - * Use e.g. stglink:float[], stglink:sink[], stglink:push[], and - stglink:pop[] to reorder patches. + * Use e.g. linkstg:float[], linkstg:sink[], linkstg:push[], and + linkstg:pop[] to reorder patches. - * Use stglink:squash[] to merge two or more patches into one. - stgsublink:squash[] pushes and pops so that the patches to be + * Use linkstg:squash[] to merge two or more patches into one. + linkstgsub:squash[] pushes and pops so that the patches to be merged are consecutive and unrelated patches aren't in the way, then makes one big patch out of the patches to be merged, and finally pushes the other patches back. @@ -422,7 +422,7 @@ commits again: $ stg commit --all -TIP: stglink:commit[] can also commit specific patches (named on the +TIP: linkstg:commit[] can also commit specific patches (named on the command line), leaving the rest alone. This can be used to retire patches as they mature, while keeping the newer and more volatile patches as patches. @@ -455,18 +455,18 @@ Getting patches upstream We've already covered how to clone a Git repository and start writing patches. As for the next step, there are two commands you might use to -get patches out of StGit: stglink:mail[] and stglink:export[]. -stglink:export[] will export your patches to a filesystem directory as +get patches out of StGit: linkstg:mail[] and linkstg:export[]. +linkstg:export[] will export your patches to a filesystem directory as one text file per patch, which can be useful if you are going to send the patches by something other than e-mail. Most of the time, though, -stglink:mail[] is what you want. +linkstg:mail[] is what you want. NOTE: Git comes with tools for sending commits via e-mail. Since StGit patches are Git commits, you can use the Git tools if you like them better for some reason. NOTE: For exporting single patches -- as opposed to a whole bunch of -them -- you could also use stglink:show[] or stglink:diff[]. +them -- you could also use linkstg:show[] or linkstg:diff[]. Mailing a patch is as easy as this: @@ -477,7 +477,7 @@ will be sent as a separate mail, with the first line of the commit message as subject line. Try mailing patches to yourself to see what the result looks like. -NOTE: stglink:mail[] uses +sendmail+ on your computer to send the +NOTE: linkstg:mail[] uses +sendmail+ on your computer to send the mails. If you don't have +sendmail+ properly set up, you can instruct it to use any SMTP server with the +$$--smtp-server$$+ flag. @@ -566,7 +566,7 @@ be added to its branches; to update your clone, run This will update all your remote branches, but won't touch your local branches. To get the latest changes into your local +master+ branch, -use stglink:rebase[]: +use linkstg:rebase[]: $ stg rebase remotes/origin/master @@ -588,7 +588,7 @@ latest version of +remotes/origin/master+. The primary reason for rebasing is to reduce the amount of conflicts between your work and others'. If one of your patches changes the same part of the same file as a patch someone else has written, you will -get a conflict when you run stglink:rebase[] the next time after the +get a conflict when you run linkstg:rebase[] the next time after the other person's patch has been accepted upstream. It is almost always less work to rebase often and resolve these one at a time, rather than a whole lot at once. After all, you have to rebase eventually; if you @@ -602,7 +602,7 @@ When your patches are accepted If and when some or all of your patches are accepted upstream, you update and rebase just like usual -- but be sure to use the -+$$--merged$$+ flag to stglink:rebase[]: ++$$--merged$$+ flag to linkstg:rebase[]: $ git remote update $ stg rebase --merged remotes/origin/master @@ -612,7 +612,7 @@ patches have been merged, at some cost in performance. The patches that had been merged will still be present in your patch stack after the rebase, but they will be empty, since the change they -added is now already present in the stack base. Run stglink:clean[] to +added is now already present in the stack base. Run linkstg:clean[] to get rid of such empty patches if you don't want them hanging around: $ stg clean @@ -630,10 +630,10 @@ It's perfectly fine for this person to not have the foggiest idea what StGit is. In that case, she'll probably apply your patches with something like +git am+, and everything will just work, exactly as if you'd used Git to send those patches. But she might be an StGit user -too, in which case she might use stglink:import[]. +too, in which case she might use linkstg:import[]. There are basically four kinds if stuff you can import with -stglink:import[]: +linkstg:import[]: 1. A patch in a file. @@ -650,14 +650,14 @@ Importing a plain patch ~~~~~~~~~~~~~~~~~~~~~~~ Importing a plain patch, such as produced by e.g. GNU +diff+, +git -diff+, +git show+, stglink:diff[], or stglink:show[], is very easy. +diff+, +git show+, linkstg:diff[], or linkstg:show[], is very easy. Just say $ stg import my-patch and you'll have a new patch at the top of your stack. -If you don't give a file name on the command line, stglink:import[] +If you don't give a file name on the command line, linkstg:import[] will read the patch from its standard input -- in other words, you can pipe a patch to it directly from the command that produces it. @@ -670,10 +670,10 @@ to override all of these things; see the man page for details. Importing several patches at once ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Some programs -- among them stglink:export[] -- will create a bunch of +Some programs -- among them linkstg:export[] -- will create a bunch of files with one patch in each, and a 'series' file (often called +series+) listing the other files in the correct order. Give -+$$--series$$+ and the name of the series file to stglink:import[], ++$$--series$$+ and the name of the series file to linkstg:import[], and it will import all the patches for you, in the correct order. @@ -685,7 +685,7 @@ Importing a patch from an e-mail is simple too: $ stg import --mail my-mail The e-mail should be in standard Git mail format (which is what e.g. -stglink:mail[] produces) -- that is, with the patch in-line in the +linkstg:mail[] produces) -- that is, with the patch in-line in the mail, not attached. The authorship info is taken from the mail headers, and the commit message is read from the 'Subject:' line and the mail body. @@ -700,12 +700,12 @@ Importing a mailbox full of patches ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Finally, in case importing one patch at a time is too much work, -stglink:import[] also accepts an entire Unix +mbox+-format mailbox, +linkstg:import[] also accepts an entire Unix +mbox+-format mailbox, either on the command line or on its standard input; just use the +$$--mbox$$+ flag. Each mail should contain one patch, and is imported just like with +$$--mail$$+. -Mailboxes full of patches are produced by e.g. stglink:mail[] with the +Mailboxes full of patches are produced by e.g. linkstg:mail[] with the +$$--mbox$$+ flag, but most mail readers can produce them too, meaning that you can copy all the patch mails you want to apply to a separate mailbox, and then import them all in one go. @@ -744,7 +744,7 @@ working tree in the form of Git commits. This means if you want to apply your changes to a tree not managed by Git, or send your changes to someone else in e-mail, you need to convert your StGit patches into normal textual diffs that can be applied with the GNU patch command. -stglink:diff[] is a powerful way to generate and view textual diffs of +linkstg:diff[] is a powerful way to generate and view textual diffs of patches managed by StGit. To view a diff of the topmost patch: @@ -752,7 +752,7 @@ To view a diff of the topmost patch: $ stg diff -r / Observe that this does not show any changes in the working directory -that have not been saved by a stgsublink:refresh[]. To view just the +that have not been saved by a linkstgsub:refresh[]. To view just the changes you've made since the last refresh, use: $ stg diff -r /top @@ -771,25 +771,25 @@ current patch: $ stg diff -r base -stglink:diff[] supports a number of other features that are very +linkstg:diff[] supports a number of other features that are very useful. Be sure to take a look at the help information for this command. To convert your StGit patches into patch files: $ stg export [--range=[[:]]] [] -stglink:export[] supports options to automatically number the patches +linkstg:export[] supports options to automatically number the patches (+-n+) or add the +.diff+ extension (+-d+). If you don't tell -stgsublink:export[] where to put the patches, it will create directory +linkstgsub:export[] where to put the patches, it will create directory named +patch-+ in your current directory, and store the patches there. To e-mail a patch or range of patches: $ stg mail [--to=...] (--all | --range=[[:]] | ) -stglink:mail[] has a lot of options, so read the output of +stg mail +linkstg:mail[] has a lot of options, so read the output of +stg mail -h+ for more information. You can also import an existing GNU diff patch file as a new StGit -patch with a single command. stglink:import[] will automatically parse +patch with a single command. linkstg:import[] will automatically parse through the patch file and extract a patch description. Use: $ stg import [] @@ -801,7 +801,7 @@ This is the equivalent of $ stg refresh -e Sometimes the patch file won't apply cleanly. In that case, -stglink:import[] will leave you with an empty StGit patch, to which +linkstg:import[] will leave you with an empty StGit patch, to which you then apply the patch file by hand using "patch -i" and your favorite editor. @@ -820,13 +820,13 @@ Templates TODO:: This section needs revising. I've only fixed the formatting. -stglink:export[] and stglink:mail[] use templates for generating the +linkstg:export[] and linkstg:mail[] use templates for generating the patch files or e-mails. The default templates are installed under +/share/stgit/templates/+ and, combined with the extra options available for these commands, should be enough for most users. The template format uses the standard Python string formatting rules. The variables available are listed in the the manual pages for each -command. stglink:mail[] can also send an initial 'cover' e-mail for +command. linkstg:mail[] can also send an initial 'cover' e-mail for which there is no default template. The +/share/stgit/examples/firstmail.tmpl+ file can be used as an example. A default description for new patches can be defined in the diff --git a/stgit/commands/__init__.py b/stgit/commands/__init__.py index 54a9326..f6cf3c3 100644 --- a/stgit/commands/__init__.py +++ b/stgit/commands/__init__.py @@ -89,6 +89,6 @@ def asciidoc_command_list(commands, f): _write_underlined(kind, '~', f) f.write('\n') for cmd, help in cmds: - f.write('stgsublink:%s[]::\n' % cmd) + f.write('linkstgsub:%s[]::\n' % cmd) f.write(' %s\n' % help) f.write('\n') diff --git a/stgit/commands/branch.py b/stgit/commands/branch.py index 3d912fc..8748c0a 100644 --- a/stgit/commands/branch.py +++ b/stgit/commands/branch.py @@ -52,20 +52,20 @@ options = [ List each branch in the current repository, followed by its branch description (if any). The current branch is prefixed with '>'. Branches that have been initialized for StGit (with - stglink:init[]) are prefixed with 's'. Protected branches are + linkstg:init[]) are prefixed with 's'. Protected branches are prefixed with 'p'."""), opt('-c', '--create', action = 'store_true', short = 'Create (and switch to) a new branch', long = """ Create (and switch to) a new branch. The new branch is already initialized as an StGit patch stack, so you do not have to run - stglink:init[] manually. If you give a committish argument, + linkstg:init[] manually. If you give a committish argument, the new branch is based there; otherwise, it is based at the current HEAD. StGit will try to detect the branch off of which the new branch is forked, as well as the remote repository from which that parent branch is taken (if any), so that running - stglink:pull[] will automatically pull new commits from the + linkstg:pull[] will automatically pull new commits from the correct branch. It will warn if it cannot guess the parent branch (e.g. if you do not specify a branch name as committish)."""), diff --git a/stgit/commands/clone.py b/stgit/commands/clone.py index efb7198..7fe9c35 100644 --- a/stgit/commands/clone.py +++ b/stgit/commands/clone.py @@ -25,12 +25,12 @@ kind = 'repo' usage = [' '] description = """ Clone a git repository into the local directory (using -stglink:clone[]) and initialise the local branch "master". +linkstg:clone[]) and initialise the local branch "master". This operation is for example suitable to start working using the "tracking branch" workflow (see link:stg[1]). Other means to setup -an StGit stack are stglink:init[] and the '--create' and '--clone' -commands of stglink:branch[]. +an StGit stack are linkstg:init[] and the '--create' and '--clone' +commands of linkstg:branch[]. The target directory will be created by this command, and must not already exist.""" diff --git a/stgit/commands/new.py b/stgit/commands/new.py index 151cfe9..2c98431 100644 --- a/stgit/commands/new.py +++ b/stgit/commands/new.py @@ -28,7 +28,7 @@ description = """ Create a new, empty patch on the current stack. The new patch is created on top of the currently applied patches, and is made the new top of the stack. Uncommitted changes in the work tree are not -included in the patch -- that is handled by stglink:refresh[]. +included in the patch -- that is handled by linkstg:refresh[]. The given name must be unique in the stack, and may only contain alphanumeric characters, dashes and underscores. If no name is given, diff --git a/stgit/commands/sink.py b/stgit/commands/sink.py index d4561ed..826668d 100644 --- a/stgit/commands/sink.py +++ b/stgit/commands/sink.py @@ -26,7 +26,7 @@ help = 'Send patches deeper down the stack' kind = 'stack' usage = ['[-t ] [-n] []'] description = """ -This is the opposite operation of stglink:float[]: move the specified +This is the opposite operation of linkstg:float[]: move the specified patches down the stack. It is for example useful to group stable patches near the bottom of the stack, where they are less likely to be impacted by the push of another patch, and from where they can be more -- 2.11.0