Browse files

new mkdoc, local, using pandoc

  • Loading branch information...
1 parent 117452d commit f27380d173b9443c1c318188643414ec00ea45a3 @sitaramc committed Dec 5, 2013
Showing with 160 additions and 166 deletions.
  1. +12 −0 common-header.html
  2. +2 −4 contrib/sskm.mkd
  3. +2 −4 contrib/ukm.mkd
  4. +2 −4 cookbook.mkd
  5. +2 −4 cust.mkd
  6. +1 −3 dev-notes.mkd
  7. +1 −1 dev-status.mkd
  8. +4 −4 emergencies.mkd
  9. +2 −4 extras/glssh.mkd
  10. +3 −5 extras/sts.mkd
  11. +2 −2 g2migr-example.mkd
  12. +3 −5 g2migr.mkd
  13. +1 −3 git-config.mkd
  14. +48 −82 1-page.pl → gitolite.mkd
  15. +1 −1 how.mkd
  16. +2 −4 install.mkd
  17. +2 −2 ips.mkd
  18. +2 −2 locking.mkd
  19. +2 −4 mirroring.mkd
  20. +50 −0 mkdoc
  21. +2 −4 non-core.mkd
  22. +1 −1 refex.mkd
  23. +3 −3 rules.mkd
  24. +1 −3 special.mkd
  25. +1 −1 syntax.mkd
  26. +1 −1 triggers.mkd
  27. +2 −4 user.mkd
  28. +2 −4 vref.mkd
  29. +0 −2 who.mkd
  30. +1 −3 why.mkd
  31. +1 −1 wild.mkd
  32. +1 −1 write-types.mkd
View
12 common-header.html
@@ -0,0 +1,12 @@
+<p style="text-align:center">
+ <a href="master-toc.html">master TOC</a>
+|
+ <a href="index.html">main page</a>
+|
+ <a href="gitolite.html">single-page</a>
+|
+ <a href="index.html#license">license</a>
+</p>
+<p style="text-align:center">
+<font color="gray">This is for gitolite "g3"; for older (v2.x) documentation click <a href="http://sitaramc.github.com/gitolite/g2/master-toc.html">here</a></font>
+</p>
View
6 contrib/sskm.mkd
@@ -1,5 +1,7 @@
# changing keys -- self service key management
+<!-- pandoc: toc -->
+
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!
View
6 contrib/ukm.mkd
@@ -1,5 +1,7 @@
# user key management
+<!-- pandoc: toc -->
+
Copyright 2012-2013 Ralf Hemmecke <ralf@hemmecke.org>.
Licensed under the [Creative Commons
@@ -15,10 +17,6 @@ below.
----
-TOC
-
-----
-
## Important Warning!
User key management undermines the fundamental principle of gitolite
View
6 cookbook.mkd
@@ -1,5 +1,7 @@
# gitolite cookbook
+<!-- pandoc: toc -->
+
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"
View
6 cust.mkd
@@ -1,5 +1,7 @@
# customising gitolite
+<!-- pandoc: toc -->
+
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.
View
4 dev-notes.mkd
@@ -1,8 +1,6 @@
# notes for developers
-TOC
-
-----
+<!-- pandoc: 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.
View
2 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):
View
8 emergencies.mkd
@@ -1,12 +1,12 @@
# help for emergencies
-----
+<!-- pandoc: toc -->
-"Don't Panic!"
+> ----
-----
+> .@red<**"Don't Panic!"**>@
-TOC
+> ----
## install/setup issues
View
6 extras/glssh.mkd
@@ -1,8 +1,6 @@
-# #glssh how gitolite uses ssh
+# how gitolite uses ssh
-TOC
-
-----
+<!-- pandoc: toc -->
Although other forms of authentications exist (see the document on
[authentication versus authorisation][auth]), ssh is the one that most git
View
8 extras/sts.mkd
@@ -1,4 +1,6 @@
-# #sts ssh troubleshooting and tips
+# ssh troubleshooting and tips
+
+<!-- pandoc: toc -->
**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
View
4 g2migr-example.mkd
@@ -1,8 +1,8 @@
# migration example
-This shows what a typical migration would look like, using a test setup.
+<!-- pandoc: toc -->
-TOC
+This shows what a typical migration would look like, using a test setup.
## existing setup
View
8 g2migr.mkd
@@ -1,14 +1,12 @@
-# #g2migr pre-migration checklist
+# pre-migration checklist
+
+<!-- pandoc: toc -->
<font color="red"> **This document is a *MUST* read if you are currently using
g2 and want to move to g3.** </font>
----
-TOC
-
-----
-
First things first: g2 will be supported for a good long time for critical
bugs, although enhancements and new features won't happen.
View
4 git-config.mkd
@@ -1,8 +1,6 @@
# "git-config" keys and values
-TOC
-
-----
+<!-- pandoc: toc -->
Here's all you want to know about setting repo-specific git-config values.
View
130 1-page.pl → gitolite.mkd 100755 → 100644
@@ -1,67 +1,9 @@
-#!/usr/bin/perl
+<!-- master mode -->
-# 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 (<DATA>) {
- 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
+<!--
+NOTE: ips, locking, progit, sskm, plus any mkds that belong to specific
+branches (cache, namespaces) are left out.
+-->
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
View
2 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?
View
6 install.mkd
@@ -11,12 +11,10 @@ followed by [setup][], then [clone][].
----
-TOC
-
-----
-
## #nnc notes and naming conventions
+<!-- pandoc: toc -->
+
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.
View
4 ips.mkd
@@ -1,5 +1,7 @@
# idiot-proof setup for gitolite
+<!-- pandoc: toc -->
+
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
View
4 locking.mkd
@@ -1,5 +1,7 @@
# locking binary files
+<!-- pandoc: toc -->
+
Locking is useful to make sure that binary files (office docs, images, ...)
don't get into a merge state. (<font color="gray">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"
View
6 mirroring.mkd
@@ -1,16 +1,14 @@
# mirroring using gitolite
+<!-- pandoc: toc -->
+
<font color="red">**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
serious system admin things, well... good luck!</font>
----
-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.
View
50 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");
View
6 non-core.mkd
@@ -1,5 +1,7 @@
# non-core features shipped with gitolite
+<!-- pandoc: toc -->
+
**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
View
2 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.
View
6 rules.mkd
@@ -1,12 +1,12 @@
-# #rules access rules
+# access rules
+
+<!-- pandoc: toc -->
**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.
View
4 special.mkd
@@ -1,8 +1,6 @@
# special features and setups
-----
-
-TOC
+<!-- pandoc: toc -->
----
View
2 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.
View
2 triggers.mkd
@@ -1,6 +1,6 @@
# gitolite triggers
-TOC
+<!-- pandoc: toc -->
## intro and sample rc excerpt
View
6 user.mkd
@@ -1,14 +1,12 @@
# what users (not admins) need to know about gitolite
+<!-- pandoc: toc -->
+
...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
View
6 vref.mkd
@@ -1,15 +1,13 @@
# virtual refs
+<!-- pandoc: toc -->
+
**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.
View
2 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
View
4 why.mkd
@@ -1,8 +1,6 @@
# why might you need gitolite
-TOC
-
-----
+<!-- pandoc: 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
View
2 wild.mkd
@@ -1,6 +1,6 @@
# "wild" repos (user created repos)
-TOC
+<!-- pandoc: toc -->
## quick introduction
View
2 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.

0 comments on commit f27380d

Please sign in to comment.