From 3ef79225fc710938867744a7cfa1029aa3cfcead Mon Sep 17 00:00:00 2001 From: Ben Lynn Date: Tue, 4 Sep 2007 02:08:20 -0700 Subject: [PATCH] Added top-level itemized lists to wiki format Clarified git vs ssh access in some parts --- Makefile | 2 +- basic.txt | 28 ++++++++++++++++--------- branch.txt | 6 +++--- clone.txt | 12 +++++++---- secrets.txt | 4 ++-- wiki2xml | 68 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++---- 6 files changed, 96 insertions(+), 24 deletions(-) diff --git a/Makefile b/Makefile index d0eb6e0..698d966 100644 --- a/Makefile +++ b/Makefile @@ -5,7 +5,7 @@ target: book TXTFILES=intro.txt basic.txt clone.txt branch.txt grandmaster.txt secrets.txt book.xml: $(TXTFILES) - cat $^ | sed 's///g' | sed 's/<\/tt>/<\/command>/g' | ./bookmake > book.xml + cat $^ | sed 's/\*\([^ *][^*]*[^ *]\)\*/\1<\/command>/g' | ./bookmake > book.xml book: book.xml book.css preface.html book/default.css xmlto -m custom-html.xsl -o book html book.xml diff --git a/basic.txt b/basic.txt index 4d4d89b..f670071 100644 --- a/basic.txt +++ b/basic.txt @@ -26,7 +26,7 @@ Tip: the hyphen after "git" may be replaced by a space if you prefer. === Add, Delete, Rename === -The above will only keep track of the files that were present when you first ran git-add. If you add new files or subdirectories, you'll have to tell Git: +The above will only keep track of the files that were present when you first ran *git-add*. If you add new files or subdirectories, you'll have to tell Git: $ git-add NEWFILES... @@ -34,7 +34,7 @@ Similarly, if you want Git to forget about certain files, maybe because you've d $ git-rm OLDFILES... -Renaming a file is the same as removing the old name and adding the new name. There's also the shortcut git-mv which has the same syntax as the mv command. For example: +Renaming a file is the same as removing the old name and adding the new name. There's also the shortcut *git-mv* which has the same syntax as the *mv* command. For example: $ git-mv OLDFILE NEWFILE @@ -58,7 +58,7 @@ Other time specifications work too. Or you can ask for the 5th-last saved state: $ git-revert "@{5}" . -Running git-log reveals that the fact that you loaded an old saved state has been recorded as new commit. In other words, Git tracks your undo and redo operations. +Running *git-log* reveals that the fact that you loaded an old saved state has been recorded as new commit. In other words, Git tracks your undo and redo operations. Sometimes you just want to go back and forget about every change past a certain point because they're all wrong. Then type: @@ -66,23 +66,27 @@ Sometimes you just want to go back and forget about every change past a certain which restores the state to a given commit and also erases all newer commits from the record permanently. -Using git-checkout is a third way to load an old state, but it's slightly more complicated because it involves branches, and will be discussed in detail later. +Using *git-checkout* is a third way to load an old state, but it's slightly more complicated because it involves branches, and will be discussed in detail later. -To take the computer game analogy again, git-revert is like loading a game and recording this fact as a new saved game, and git-reset --hard is like loading an old save and deleting all saved games newer than the one just loaded. +To take the computer game analogy again: -Lastly, git-checkout is like loading an old game, but if you play on, the game state will deviate from the newer saves you made the first time around. Any saved games you make now will end up in a separate branch representing the alternate reality you have entered. We describe how to deal with this later. +- *git-revert* is like loading a game and recording this fact as a new saved game, + +- *git-reset --hard* is like loading an old save and deleting all saved games newer than the one just loaded, and + +- *git-checkout* is like loading an old game, but if you play on, the game state will deviate from the newer saves you made the first time around. Any saved games you make now will end up in a separate branch representing the alternate reality you have entered. We describe how to deal with this later. == Dowloading Files == If a project uses Git to manage its files, you can get a copy with: - $ git-clone server:/path/to/files + $ git-clone git://server/path/to/files -We'll have a lot more to say about the clone command later. +We'll have a lot more to say about the *clone* command later. == Keeping Up-to-date == -If a project uses Git to manage its files, and you've already downloaded a copy using git-clone, you can upgrade to the latest released version with: +If a project uses Git to manage its files, and you've already downloaded a copy using *git-clone*, you can upgrade to the latest released version with: $ git-pull @@ -100,7 +104,11 @@ Then tell your users to type $ git-clone your.computer:/path/to/script -to download your script. From now on, every time your script is ready for release, type: +to download your script. This assumes they have ssh access. If not, run *git-daemon* and tell your users to type + + $ git-clone git://your.computer/path/to/script + +From now on, every time your script is ready for release, type: $ git-commit -a -m "next release" diff --git a/branch.txt b/branch.txt index 2d1d002..5ef663f 100644 --- a/branch.txt +++ b/branch.txt @@ -8,7 +8,7 @@ Interrupting your train of thought can be detrimental to your productivity, and But cloning still entails copying the whole working directory as well as the entire history up to the given point. Even though Git reduces the cost of this with file sharing and hard links, the project files themselves must be recreated in their entirety in the new working directory, so we may edit them. -Happily, Git has a better tool for these situations that is much faster and more space-efficient than cloning: git-branch. +Happily, Git has a better tool for these situations that is much faster and more space-efficient than cloning: *git-branch*. == The Boss Key == @@ -119,13 +119,13 @@ Type: to list all the branches. There is always a branch named "master", and you start here by default. Some advocate leaving the "master" branch untouched and creating new branches for your own edits. -The branch command can also do other operations with branches. See git help branch for details. +The branch command can also do other operations with branches. See *git help branch* for details. == Work How You Want == Several Linux window managers allow you to have multiple desktops, which means you can instantly view a different state of the desktop. Git branching is like multiple desktops for your working directory. Continuing this analogy, Git cloning is like attaching another monitor on which you can open more windows. -Perhaps a better example is the famous [[http://www.gnu.org/software/screen/][screen]] utility. This gem allows you to create, destroy and switch between multiple terminal sessions in the same terminal. Instead of opening new terminals (clone), you can use the same one if you run screen (branch). In fact, you can do a lot more with screen but that's a topic for another day. +Perhaps a better example is the famous [[http://www.gnu.org/software/screen/][*screen*]] utility. This gem allows you to create, destroy and switch between multiple terminal sessions in the same terminal. Instead of opening new terminals (clone), you can use the same one if you run *screen* (branch). In fact, you can do a lot more with *screen* but that's a topic for another day. Web browsers like [[http://www.mozilla.com/][Mozilla Firefox]] allow you to open multitple tabs and multiple windows which are analogous to branching and cloning in Git. Being able to do both easily makes for a better user experience. diff --git a/clone.txt b/clone.txt index 07d3b6c..7790233 100644 --- a/clone.txt +++ b/clone.txt @@ -6,7 +6,7 @@ In Git and other distributed version control systems, cloning is the standard op == Sync Computers == -This is the reason I first used Git. I can tolerate making tarballs or using rsync for backups and basic syncing. The problem was sometimes I'd edit on my laptop, other times on my desktop, and they may not have talked to each other in between. +This is the reason I first used Git. I can tolerate making tarballs or using *rsync* for backups and basic syncing. The problem was sometimes I'd edit on my laptop, other times on my desktop, and they may not have talked to each other in between. Initialize a Git repository and commit your files as above on one machine. Then on the other: @@ -41,6 +41,10 @@ On the central server, initialize an empty Git repository with some name: $ GIT_DIR=proj.git git-init-db +and start the Git daemon if necessary: + + $ git-daemon --detach + Some public hosts, such as [[http://repo.or.cz][repo.or.cz]], will have a different method for setting up the initially empty Git repository, such as filling in a form on a webpage. Push your project to the central server with: @@ -49,7 +53,7 @@ Push your project to the central server with: We're ready. To check out source, a developer types - $ git clone central.server:/path/to/proj.git + $ git clone git://central.server/path/to/proj.git After making changes, the code is checked in to the main server by: @@ -71,7 +75,7 @@ You might not use most of Git's features in a small project, but there is nothin Sick of the way a project is being run? Think you could do a better job? Then on your server: - $ git clone main.server:/path/to/files + $ git clone git://main.server/path/to/files Next tell everyone to check out your fork of the project at your server. @@ -93,7 +97,7 @@ Say you want to work on several features in parallel. Then after committing your $ git-clone --local --shared . /some/new/directory -The options can be written as -l -s instead, which I like to think of as an acronym for "Light Speed"! +The options can be written as *-l -s* instead, which I like to think of as an acronym for "Light Speed"! Git exploits hard links and file sharing as much as possible to create this clone. Subsequently, this clone is unsuitable as a backup. However, it's ready in a flash, and you can now work on two independent features simultaneously. For example, you can edit one clone while the other is compiling. diff --git a/secrets.txt b/secrets.txt index 645a896..e382f5f 100644 --- a/secrets.txt +++ b/secrets.txt @@ -8,7 +8,7 @@ How can Git be so unobtrusive? Aside from occasional commits and merges, you can Other version control systems don't let you forget about them. Permissions of files may be read-only unless you explicity tell the server which files you intend to edit. The central server might be keeping track of who's checked out which code, and when. When the network goes down, you'll soon suffer. Developers constantly struggle with virtual red tape and bureaucracy. -The secret is the ".git" directory in your working directory. Git keeps the history of your project here. The initial "." stops it showing up in ls listings. Except when you're pushing and pulling changes, all version control operations operate within this directory. +The secret is the ".git" directory in your working directory. Git keeps the history of your project here. The initial "." stops it showing up in *ls* listings. Except when you're pushing and pulling changes, all version control operations operate within this directory. You have total control over the fate of your files because Git doesn't care what you do to them. Git can easily recreate a saved state from ".git" at any time. @@ -72,6 +72,6 @@ Actually, every clone could maintain such a counter, but this would probably not === Automatic Compression === -To save space, git-gc should be run once in a while. Some complain because this must be done manually. +To save space, *git-gc* should be run once in a while. Some complain because this must be done manually. If this is a major concern, scripts should be written to run this program automatically. Ideally it should occur when during periods of little activity. diff --git a/wiki2xml b/wiki2xml index c6abb91..2315f5d 100755 --- a/wiki2xml +++ b/wiki2xml @@ -15,7 +15,7 @@ func close_section() { } func close_until(i) { - close_block() + close_lists() while (stack_i > i) { close_section() } @@ -36,21 +36,73 @@ func in_block(s) { } } +func ul_item() { + if (in_list) { + close_block() + print "" + } else { + in_list = 1 + print "" + } + print "" +} + +func close_lists() { + close_block() + if (in_list) { + print "" + print "" + in_list = 0 + list_indent = 0 + } +} + BEGIN { stack_i = 0 } +# empty lines = close block /^ *$/ { close_block() next } +# lists/stuff that goes in tags +# if matches a previous indentation level it's a list +# otherwise it should have higher indentation level +# and belongs in tag + /^ / { - in_block("screen") - print $0 - next + n = length() + # must use gensub because length() doesn't seem to change after sub() + tmp = gensub("^ *", "", 1) + n -= length(tmp) + $0 = tmp + if (list_indent == n) { + was_list_item = 1 + } else if (list_indent < n) { + in_block("screen") + print $0 + next + } else { + print "funny indent level" + print $0 + next + } } +/^-/ { + was_list_item = 1 + n = length() + # must use gensub because length() doesn't seem to change after sub() + tmp = gensub("^- *", "", 1) + $0 = tmp + n -= length(tmp) + list_indent = n + ul_item() +} + +# replace " with prettier Unicode open/close double quotes /"/ { while (match($0, "\"")) { sub("\"", "\\“") @@ -65,6 +117,8 @@ BEGIN { } } +# headings + /^ *===.*===$/ { gsub(" *=== *","") close_until(2) @@ -89,13 +143,19 @@ BEGIN { next } +# links /\[\[/ { gsub("\\[\\[", "") gsub("]]", "") } +# default = paragraph { + if (!was_list_item) { + close_lists() + } + was_list_item = 0 in_block("para") print $0 } -- 2.11.4.GIT