From f27380d173b9443c1c318188643414ec00ea45a3 Mon Sep 17 00:00:00 2001 From: Sitaram Chamarty Date: Thu, 5 Dec 2013 21:59:20 +0530 Subject: [PATCH] new mkdoc, local, using pandoc --- common-header.html | 12 ++++ contrib/sskm.mkd | 6 +- contrib/ukm.mkd | 6 +- cookbook.mkd | 6 +- cust.mkd | 6 +- dev-notes.mkd | 4 +- dev-status.mkd | 2 +- emergencies.mkd | 8 +-- extras/glssh.mkd | 6 +- extras/sts.mkd | 8 +-- g2migr-example.mkd | 4 +- g2migr.mkd | 8 +-- git-config.mkd | 4 +- 1-page.pl => gitolite.mkd | 130 ++++++++++++++------------------------ how.mkd | 2 +- install.mkd | 6 +- ips.mkd | 4 +- locking.mkd | 4 +- mirroring.mkd | 6 +- mkdoc | 50 +++++++++++++++ non-core.mkd | 6 +- refex.mkd | 2 +- rules.mkd | 6 +- special.mkd | 4 +- syntax.mkd | 2 +- triggers.mkd | 2 +- user.mkd | 6 +- vref.mkd | 6 +- who.mkd | 2 - why.mkd | 4 +- wild.mkd | 2 +- write-types.mkd | 2 +- 32 files changed, 160 insertions(+), 166 deletions(-) create mode 100644 common-header.html rename 1-page.pl => gitolite.mkd (54%) mode change 100755 => 100644 create mode 100755 mkdoc diff --git a/common-header.html b/common-header.html new file mode 100644 index 0000000..ffddae0 --- /dev/null +++ b/common-header.html @@ -0,0 +1,12 @@ +

+ master TOC +| + main page +| + single-page +| + license +

+

+This is for gitolite "g3"; for older (v2.x) documentation click here +

diff --git a/contrib/sskm.mkd b/contrib/sskm.mkd index 832eb73..80cb598 100644 --- a/contrib/sskm.mkd +++ b/contrib/sskm.mkd @@ -1,5 +1,7 @@ # changing keys -- self service key management + + Copyright: Jeff Mitchell (jmitchell@kde.org). Licensed under CC-BY-NC-SA unported 3.0, http://creativecommons.org/licenses/by-nc-sa/3.0/ @@ -11,10 +13,6 @@ The key management is done using a command called `sskm`. This command must be ---- -TOC - ----- - ## Important! There are a few things that you should know before using the key management system. Please do not ignore this section! diff --git a/contrib/ukm.mkd b/contrib/ukm.mkd index d43d938..f0a98e8 100644 --- a/contrib/ukm.mkd +++ b/contrib/ukm.mkd @@ -1,5 +1,7 @@ # user key management + + Copyright 2012-2013 Ralf Hemmecke . Licensed under the [Creative Commons @@ -15,10 +17,6 @@ below. ---- -TOC - ----- - ## Important Warning! User key management undermines the fundamental principle of gitolite diff --git a/cookbook.mkd b/cookbook.mkd index dc86dbf..dee45dd 100644 --- a/cookbook.mkd +++ b/cookbook.mkd @@ -1,5 +1,7 @@ # gitolite cookbook + + Documentation is meant to be as complete as possible, which means it attempts to cover all situations and scenarios. That makes it harder to read. @@ -16,10 +18,6 @@ documentation before asking for help. In particular, the [basic][] and ---- -TOC - ----- - ## #cb-admin administration ### separating "key admin" from "repo admin" diff --git a/cust.mkd b/cust.mkd index 4700194..c8922aa 100644 --- a/cust.mkd +++ b/cust.mkd @@ -1,5 +1,7 @@ # customising gitolite + + Much of gitolite (g3)'s functionality comes from programs and scripts that are not considered "core". This keeps the core simpler, and allows you to enhance gitolite for your own purposes without too much fuss. (As an extreme example, @@ -18,10 +20,6 @@ Here's how to find out more: ---- -TOC - ----- - ## #ncintro introduction There are 5 basic types of non-core programs. diff --git a/dev-notes.mkd b/dev-notes.mkd index b109685..fd0a82e 100644 --- a/dev-notes.mkd +++ b/dev-notes.mkd @@ -1,8 +1,6 @@ # notes for developers -TOC - ----- + Gitolite has a huge bunch of existing features that gradually need to be moved over. Plus you may want to write your own programs to interact with it. diff --git a/dev-status.mkd b/dev-status.mkd index f6de0a3..6a5f5e2 100644 --- a/dev-status.mkd +++ b/dev-status.mkd @@ -1,4 +1,4 @@ -# #dev-status g3 development status +# g3 development status Not yet done (will be tackled in this order unless someone asks): diff --git a/emergencies.mkd b/emergencies.mkd index 220c379..b181b50 100644 --- a/emergencies.mkd +++ b/emergencies.mkd @@ -1,12 +1,12 @@ # help for emergencies ----- + -"Don't Panic!" +> ---- ----- +> .@red<**"Don't Panic!"**>@ -TOC +> ---- ## install/setup issues diff --git a/extras/glssh.mkd b/extras/glssh.mkd index 4da82d6..8580caa 100644 --- a/extras/glssh.mkd +++ b/extras/glssh.mkd @@ -1,8 +1,6 @@ -# #glssh how gitolite uses ssh +# how gitolite uses ssh -TOC - ----- + Although other forms of authentications exist (see the document on [authentication versus authorisation][auth]), ssh is the one that most git diff --git a/extras/sts.mkd b/extras/sts.mkd index 22d5727..991aff8 100644 --- a/extras/sts.mkd +++ b/extras/sts.mkd @@ -1,4 +1,6 @@ -# #sts ssh troubleshooting and tips +# ssh troubleshooting and tips + + **This document must be read in full the first time. If you start from some nice looking section in the middle it may not help you unless you're already @@ -10,10 +12,6 @@ tricks that gitolite can do. ---- -TOC - ----- - ## IMPORTANT -- READ THIS FIRST ### caveats diff --git a/g2migr-example.mkd b/g2migr-example.mkd index 9bb3221..b7c773a 100644 --- a/g2migr-example.mkd +++ b/g2migr-example.mkd @@ -1,8 +1,8 @@ # migration example -This shows what a typical migration would look like, using a test setup. + -TOC +This shows what a typical migration would look like, using a test setup. ## existing setup diff --git a/g2migr.mkd b/g2migr.mkd index 8b124db..82cb3b9 100644 --- a/g2migr.mkd +++ b/g2migr.mkd @@ -1,14 +1,12 @@ -# #g2migr pre-migration checklist +# pre-migration checklist + + **This document is a *MUST* read if you are currently using g2 and want to move to g3.** ---- -TOC - ----- - First things first: g2 will be supported for a good long time for critical bugs, although enhancements and new features won't happen. diff --git a/git-config.mkd b/git-config.mkd index 82fe6d2..efeeb56 100644 --- a/git-config.mkd +++ b/git-config.mkd @@ -1,8 +1,6 @@ # "git-config" keys and values -TOC - ----- + Here's all you want to know about setting repo-specific git-config values. diff --git a/1-page.pl b/gitolite.mkd old mode 100755 new mode 100644 similarity index 54% rename from 1-page.pl rename to gitolite.mkd index f5f6993..4ca3f3a --- a/1-page.pl +++ b/gitolite.mkd @@ -1,67 +1,9 @@ -#!/usr/bin/perl + -# a rather simple script to produce a single mkd file out of all the docs. -# -# the major effort is in coming up with the best sequence of MKD files for -# reading. It's kinda subjective... - -# typically run as `./1-page.pl`; produces "gitolite.mkd" (hardcoded) - -open(STDOUT, ">", "gitolite.mkd"); - -my $out = ''; -my $base; -my %map; - -while () { - if (/^include (\S+)$/) { - $out .= one($1) - } else { - $out .= $_; - } -} - -sub one { - my $mkd = shift; - - my $base = $mkd; - $base =~ s(.*/)(); - $base =~ s(.mkd$)(); - - my $out = ''; - - # for each mkd - for (`cat $mkd`) { - - # ignore internal HRs and TOCs - next if /^----$/ or /^TOC$/; - # add anchor to h1 lines that don't already have one - s/^# (?!#)/# #$base /; - # increase the outline level all through by 1 - s/^#/##/; - # prefix all anchor texts with basename and remember the mapping - $map{$2} = "$base-$2" if s/^(#+) #(\S+) /$1 #$base-$2 /; - - $out .= $_; - } - $out .= "\n\n----\n\n"; - - return $out; -} - -# apply the mapping to references [like][this] etc., although you have to fix -# [this][] to look like [this][this] for convenience. -$out =~ s/\[(\S+?)\]\[\]/[$1][$1]/g; -$out =~ s/\]\[(\S+?)\]/"][" . ( $map{$1} || $1 ) . "]"/ge; - -print $out; - -# note: ips, locking, progit, sskm, plus any mkds that belong to specific -# branches (cache, namespaces) are left out. - -__DATA__ - -#title Gitolite docs in one big page + This contains **all** of gitolite's documentation in one page. Useful for people who'd rather Ctrl-F around than click around :-) @@ -84,9 +26,6 @@ sub one { * the main page -- see link at the top * the "master table of contents" -- see link at the top * the graphical overviews: [basic][] and [advanced][] - * a truly humungous index of all the section headings in *this* document - appears at the end, cleverly moved there from its traditional place to - avoid scaring people away! Enjoy! @@ -95,94 +34,121 @@ sub one { # #s1 basics, quick links, and help include index.mkd + include testing.mkd + include qi.mkd + include user.mkd + include users.mkd + include repos.mkd + include groups.mkd + include emergencies.mkd + include WARNINGS.mkd # #s2 detailed installation and access rules include install.mkd + include setup.mkd + include clone.mkd + include syntax.mkd + include admin.mkd + include rules.mkd + include refex.mkd + include write-types.mkd # #s3 the rc file, git-config, and options include rc.mkd + include git-config.mkd + include options.mkd + include external.mkd # #s4 wild repos, mirroring, and other features include wild.mkd + include mirroring.mkd + include deleg.mkd + include special.mkd + include rare.mkd # #s5 smart http include http.mkd + include contrib/ssh-and-http.mkd # #s6 customising gitolite include cust.mkd + include non-core.mkd + include dev-notes.mkd + include vref.mkd + include triggers.mkd # #s7 ssh include extras/ssh.mkd + include extras/auth.mkd + include extras/glssh.mkd + include extras/sts.mkd + include contrib/putty.mkd # #s8 odds and ends include how.mkd + include why.mkd + include who.mkd + include g3why.mkd + include dev-status.mkd + include files.mkd + include extras/regex.mkd + include perf.mkd + include extras/README-emacs.mkd # #s9 migration include migr.mkd + include g2migr.mkd -include g2incompat.mkd -include g2migr-example.mkd -include gsmigr.mkd -**THE END** +include g2incompat.mkd ----- +include g2migr-example.mkd -TOC - -[s1]: gitolite.html#s1 -[s2]: gitolite.html#s2 -[s3]: gitolite.html#s3 -[s4]: gitolite.html#s4 -[s5]: gitolite.html#s5 -[s6]: gitolite.html#s6 -[s7]: gitolite.html#s7 -[s8]: gitolite.html#s8 -[s9]: gitolite.html#s9 +include gsmigr.mkd diff --git a/how.mkd b/how.mkd index a46279f..d535bf3 100644 --- a/how.mkd +++ b/how.mkd @@ -3,7 +3,7 @@ You'll appreciate this more if you first read the [try it and see][tias] page (don't worry, it's very short and quick). -[tias]: http://sitaramc.github.com/1-basic-usage/tias.html +[tias]: http://gitolite.com/tias.html ## what does a "gitolite repo" look like? diff --git a/install.mkd b/install.mkd index 1e7103b..f8c3b18 100644 --- a/install.mkd +++ b/install.mkd @@ -11,12 +11,10 @@ followed by [setup][], then [clone][]. ---- -TOC - ----- - ## #nnc notes and naming conventions + + Gitolite uses a single "real" (i.e., unix) user to provide secure access to git repos to any number of "virtual" users, without giving them a shell. diff --git a/ips.mkd b/ips.mkd index be491cf..df69bf8 100644 --- a/ips.mkd +++ b/ips.mkd @@ -1,5 +1,7 @@ # idiot-proof setup for gitolite + + If I gave you this link to read, it most likely means either: * (most common reason) you got really confused by [ssh][] @@ -12,8 +14,6 @@ realised that this is also useful for (a) people for whom English is not the first language and (b) people who really should not be doing technical work at this level, but are forced to do it by circumstances. -TOC - ## pre-requisites * any Linux machine on which git has already been installed diff --git a/locking.mkd b/locking.mkd index eca1f6a..ba14e63 100644 --- a/locking.mkd +++ b/locking.mkd @@ -1,5 +1,7 @@ # locking binary files + + Locking is useful to make sure that binary files (office docs, images, ...) don't get into a merge state. (If you think it's not a big deal, you have never manually merged independent changes to an ODT or @@ -21,8 +23,6 @@ containing source code. ---- -TOC - ## problem description Our users are alice, bob, and carol. Our repo is foo. It has some "odt" diff --git a/mirroring.mkd b/mirroring.mkd index 7c68d1a..4044e02 100644 --- a/mirroring.mkd +++ b/mirroring.mkd @@ -1,5 +1,7 @@ # mirroring using gitolite + + **WARNING** existing gitolite mirroring users please note: **there are [significant changes][g2i-mirroring]** in syntax and usage compared to g2. If you're not the kind who reads documentation before doing @@ -7,10 +9,6 @@ serious system admin things, well... good luck! ---- -TOC - ----- - Mirroring is simple: you have one "master" server and one or more "slave" servers. The slaves get updates only from the master; to the rest of the world they are at best read-only. diff --git a/mkdoc b/mkdoc new file mode 100755 index 0000000..6581912 --- /dev/null +++ b/mkdoc @@ -0,0 +1,50 @@ +#!/usr/bin/perl +use strict; +use warnings; +use 5.10.0; + +# run from gitolite-doc as "./mkdoc" + +# my $OUTDIR = "/tmp/doc2"; +my $OUTDIR = "$ENV{HOME}/imli/tech/repos/sitaramc.github.com/gitolite"; +system("rm $OUTDIR/*.html"); +system("rm -rf $OUTDIR/images"); +system("mkdir $OUTDIR/images"); + +my @mkd = `find . -name "*.mkd" | sort`; +chomp(@mkd); +@ARGV = @mkd unless @ARGV; + +my $linkrefs = ''; +my $base; +my %seen; +while (<>) { + unless ( $seen{$ARGV}++ ) { + # on each change of file, compute the base name... + $base = ( $ARGV =~ m(([^/]+)\.mkd) ? $1 : '' ); + # ...and add linkref to the first line if it's a header line + if ( /^#/ and not( /{#\S+}/ or /^#+ #(\S+)/ ) ) { # XXX last clause is transition code + $linkrefs .= "\[$base\]: $base.html\n"; + } + } + + # now add linkrefs for everything else + if ( /^#+ .* \{#(\S+)\}/ or /^#+ #(\S+) / ) { # XXX last clause is transition code + $linkrefs .= "\[$1\]: $base.html\#$1\n"; + } +} + +for (@mkd) { + m(([^/]+)\.mkd) or die "bad mkd file: '$_'"; + $base = $1; + next if $base eq 'gitolite'; # single page stuff needs different treatment + + open( my $mdp, "|-", "cat $_ - | md-pandoc html > $OUTDIR/$base.html" ) or die 1; + print $mdp "\n" . $linkrefs; + close $mdp; +} +system("md-pandoc html < gitolite.mkd > $OUTDIR/gitolite.html"); + +# send manually created HTML pages and images +system("cp html/*.html $OUTDIR"); +system("cp images/* $OUTDIR/images"); diff --git a/non-core.mkd b/non-core.mkd index 539fbfe..fdb3ecd 100644 --- a/non-core.mkd +++ b/non-core.mkd @@ -1,5 +1,7 @@ # non-core features shipped with gitolite + + **Important Notes on "non-core" features**: 1. The [customisation][cust] document is the starting point for all @@ -26,10 +28,6 @@ ---- -TOC - ----- - ## commands This is a list of commands that are available in gitolite, with brief diff --git a/refex.mkd b/refex.mkd index 1eb0f7a..a578648 100644 --- a/refex.mkd +++ b/refex.mkd @@ -1,4 +1,4 @@ -## #refex matching a ref and a refex +## matching a ref and a refex A refex is a word I made up to mean "a regex that matches a ref". If you know [regular expressions][regex] you're halfway there. diff --git a/rules.mkd b/rules.mkd index 7d0743f..7d9ded5 100644 --- a/rules.mkd +++ b/rules.mkd @@ -1,12 +1,12 @@ -# #rules access rules +# access rules + + **NOTE**: In the following description, "user" means "user or a [group][groups] that he/she is a member of", and "repo" means "repo, or a group that it is a member of, or a ([wild][] repo) pattern that matches it, or a group that contains a pattern that matches it". -TOC - ## what do rules look like Here's an example ruleset. diff --git a/special.mkd b/special.mkd index 72705da..d842ffb 100644 --- a/special.mkd +++ b/special.mkd @@ -1,8 +1,6 @@ # special features and setups ----- - -TOC + ---- diff --git a/syntax.mkd b/syntax.mkd index a74f17b..e31f4fa 100644 --- a/syntax.mkd +++ b/syntax.mkd @@ -1,4 +1,4 @@ -# #syntax basic syntax +# basic syntax In general, everything is **space separated**; there are no commas, semicolons, etc., in the syntax. diff --git a/triggers.mkd b/triggers.mkd index c388e02..da11f3d 100644 --- a/triggers.mkd +++ b/triggers.mkd @@ -1,6 +1,6 @@ # gitolite triggers -TOC + ## intro and sample rc excerpt diff --git a/user.mkd b/user.mkd index 3e3c877..d797679 100644 --- a/user.mkd +++ b/user.mkd @@ -1,14 +1,12 @@ # what users (not admins) need to know about gitolite + + ...written for the one guy in the world no one will think of as "just a normal user" ;-) ---- -TOC - ----- - ## accessing gitolite The most common setup is based on ssh, where your admin asks you to send him diff --git a/vref.mkd b/vref.mkd index ed1603b..ed0e3a8 100644 --- a/vref.mkd +++ b/vref.mkd @@ -1,15 +1,13 @@ # virtual refs + + **IMPORTANT**: fallthru is success in VREFs, unlike the normal refs. That won't make sense until you read further, but I had to put it up here for folks who stop reading halfway! ---- -TOC - ----- - VREFs are a mechanism to add additional constraints to a push. Here's an example to start you off. diff --git a/who.mkd b/who.mkd index dfe1149..de743d6 100644 --- a/who.mkd +++ b/who.mkd @@ -55,8 +55,6 @@ users as well. [gentoo1]: http://archives.gentoo.org/gentoo-dev/msg_2812c9b9e768f64b46360ab17b9d0024.xml [gentoo2]: http://www.gentoo.org/proj/en/overlays/ -[ldap]: http://github.com/sitaramc/gitolite/blob/pu/contrib/ldap - **kernel.org**, the official distribution point for the Linux kernel, is the latest (as of 2011-10) high-visibility installation. According to [this email][ko-ann] to the lkml, kernel.org decided to use gitolite for access diff --git a/why.mkd b/why.mkd index 50f14da..05c1b98 100644 --- a/why.mkd +++ b/why.mkd @@ -1,8 +1,6 @@ # why might you need gitolite -TOC - ----- + Git by itself does not do any access control -- it relies on the transport medium to do authentication ("who are you?"), and on OS file permissions to do diff --git a/wild.mkd b/wild.mkd index 1bb86d5..d4d6892 100644 --- a/wild.mkd +++ b/wild.mkd @@ -1,6 +1,6 @@ # "wild" repos (user created repos) -TOC + ## quick introduction diff --git a/write-types.mkd b/write-types.mkd index e1f9629..f6bc8b4 100644 --- a/write-types.mkd +++ b/write-types.mkd @@ -1,4 +1,4 @@ -# #write-types different types of write operations +# different types of write operations Git supplies enough information to the update hook to be able to distinguish several types of writes.