Skip to content

Commit

Permalink
Improved code blocks throughout text.
Browse files Browse the repository at this point in the history 
- use sha1 signatures to only generate/upload changed examples
- untranslated examples removed from git, they now link to main:translate
- listings now turned into source files in language directory
- source files marked-up using Pygmentize
- source code in text now shown as collapsible blocks (not listings)
- language scoreboard for front-page is now generated automatically
- make_guide script now uses ztools/wdput instead of its own sendpage.py tool
  • Loading branch information
@hintjens
hintjens committed Mar 27, 2011
1 parent 24a1203 commit 518807b
Show file tree
Hide file tree
Showing 1,006 changed files with 742 additions and 10,890 deletions.
320 changes: 320 additions & 0 deletions .signatures
View file

Large diffs are not rendered by default.

30 changes: 8 additions & 22 deletions bin/make_guide
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,30 +2,16 @@
#
# Generates and uploads the Guide in main languages
#
export Z2W_LANG=C
export Z2W_DIAGRAMS=1
echo "[[include page:chapter1]]" > all.wd
echo "[[include page:chapter2]]" >> all.wd
echo "[[include page:chapter3]]" >> all.wd
echo "[[include page:chapter4]]" >> all.wd
echo "[[include page:chapter5]]" >> all.wd
bin/z2w chapter*.txt
python bin/sendpage.py page all "ØMQ - The Guide"
python bin/sendpage.py page chapter1 "Chapter 1"
python bin/sendpage.py page chapter2 "Chapter 2"
python bin/sendpage.py page chapter3 "Chapter 3"
python bin/sendpage.py page chapter4 "Chapter 4"

export Z2W_LANG=PHP
export Z2W_DIAGRAMS=0
echo "[[include php:chapter1]]" > all.wd
echo "[[include php:chapter2]]" >> all.wd
echo "[[include php:chapter3]]" >> all.wd
echo "[[include php:chapter4]]" >> all.wd
bin/z2w chapter*.txt
python bin/sendpage.py php all "ØMQ - The Guide - PHP"
python bin/sendpage.py php chapter1 "Chapter 1"
python bin/sendpage.py php chapter2 "Chapter 2"
python bin/sendpage.py php chapter3 "Chapter 3"
python bin/sendpage.py php chapter4 "Chapter 4"

rm *.wd wdtemp.txt
wdput zguide page all "ØMQ - The Guide"
wdput zguide page chapter1 "Chapter 1"
wdput zguide page chapter2 "Chapter 2"
wdput zguide page chapter3 "Chapter 3"
wdput zguide page chapter4 "Chapter 4"
sh ./upload.sh
rm *.wd wdtemp.txt upload.sh
255 changes: 157 additions & 98 deletions bin/z2w
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,21 +8,25 @@
#
# Creates Wikidot file as specified by .output and images in images/.
#
# Dependencies (Ubuntu 10.10 packages):
# pygmentize
# imagemagick (mogrify tool)
#
# By Pieter Hintjens, free for remixing without conditions.
# Images are stored in the github repository at
# https://github.com/imatix/zguide
#
require 'sflcvdp.pl'; # SFL date picture formatting

@languages = ('Ada', 'Basic', 'C', 'C++', 'C#', 'Common Lisp', 'Erlang',
@languages = ('Ada', 'Basic', 'C', 'C++', 'C#', 'CommonLisp', 'Erlang',
'Go', 'Haskell', 'Java', 'Lua', 'Objective-C', 'ooc',
'Perl', 'PHP', 'Python', 'Ruby');
%extension = ('Ada' => 'ada',
'Basic' => 'bas',
'C' => 'c',
'C++' => 'cpp',
'C#' => 'cs',
'Common Lisp' => 'lisp',
'CommonLisp' => 'lisp',
'Erlang' => 'erl',
'Go' => 'go',
'Haskell' => 'hs',
Expand All @@ -36,13 +40,10 @@ require 'sflcvdp.pl'; # SFL date picture formatting
'Racket' => 'rkt',
'Ruby' => 'rb' );

$source = $ENV {Z2W_LANG} || "C";
printf "Generating $source version of Guide...\n";

$make_diagrams = $ENV {'Z2W_DIAGRAMS'};
printf "Generating the Guide...\n";

# Ensure all languages have an examples directory
foreach (@languages) {
foreach (@languages, "listings") {
$translations {$_} = 0;
if (!-d "examples/$_") {
mkdir ("examples/$_");
Expand All @@ -55,12 +56,16 @@ foreach (@languages) {
}
}
$examples = 0;
$listings = 0;

die "Can't create wdtemp.txt: $!"
unless open (OUTPUT, ">wdtemp.txt");
die "Can't create images.html: $!"
unless open (IMAGES, ">images.html");
die "Can't create upload.sh: $!"
unless open (UPLOAD, ">upload.sh");

signatures_load ();
writeln ('[!-- Generated documentation file, do not edit --]');
print IMAGES "<html>\n";

Expand Down Expand Up @@ -109,89 +114,46 @@ while (<>) {
writeln ("[[/div]]");
writeln ("[[/div]]");
}
# Process literal codeblock
elsif (/\[\[code filename=\"(.+)\"\]\]/) {
$filename = $1;
writeln ($_);

# Discard any real contents of code block
# Process unnamed code listing
elsif (/\[\[code\s+language=\"(.+)\"\]\]/) {
$listings++;
$title = "Listing $listings";
$name = "listing_$listings";
$language = $1;
$filename = "examples/$language/$name.$extension{$language}";
die "Can't create $filename: $!"
unless open (LISTING, ">$filename");
while (<>) {
last if /\[\[\/code\]\]/;
print "W: discarding $type code for $filename\n";
print LISTING $_;
}
die "Can't open $filename: $!"
unless open (SOURCE, $filename);
print OUTPUT $_
while <SOURCE>;
close (SOURCE);
writeln ('[[/code]]');
process_one_language ($title, $name, $language, 1);
}
# Process named codeblock
elsif (/\[\[code type=\"example\" title=\"(.+)\" name=\"(.+)\"\]\]/) {
elsif (/\[\[code\s+type=\"example\"\s+title=\"([^"]+)\"\s+name=\"([^"]+)\"(\s+language=\"([^"]+)\")?\]\]/) {
$title = $1;
$name = $2;
writeln ($_);

$language = $4;
if ($language) {
process_one_language ($title, $name, $language, 1);
}
else {
$missing = "";
foreach $language (@languages) {
if (process_one_language ($title, $name, $language, 0)) {
$translations {$language} += 1;
}
}
if ($missing) {
writeln ("[/main:translate Contribute translation in $missing...]");
}
$examples++;
}
# Discard any real contents of code block
while (<>) {
last if /\[\[\/code\]\]/;
print "W: discarding code for $title - $name\n";
}
$filename = get_filename ($name, $source);
die "Can't open $filename: $!"
unless open (SOURCE, $filename);
print OUTPUT $_
while <SOURCE>;
close (SOURCE);
writeln ('[[/code]]');
writeln ('[[>]]');
writeln ($filename);
writeln ('[[collapsible show="All languages" hide="Hide languages"]]');

foreach (@languages) {
$filename = get_filename ($name, $_);

# Create empty example if necessary
if (-f $filename) {
$missing = `egrep -c 'No-one has translated' '$filename'`;
}
else {
$missing = 1;
die "Can't open $filename: $!"
unless open (SOURCE, ">$filename");
print SOURCE<<"EOF";
No-one has translated the $name example into $_ yet. Be the first to create
$name in $_ and get one free Internet! If you're the author of the $_
binding, this is a great way to get people to use 0MQ in $_.
To submit a new translation email it to $symbols{EMAIL}. Please:
* Stick to identical functionality and naming used in examples so that readers
can easily compare languages.
* You MUST place your name as author in the examples so readers can contact you.
* You MUST state in the email that you license your code under the MIT/X11
license.
Subscribe to the email list at $symbols{LIST}.
EOF
close (SOURCE);
}
# Add link in list, italic if missing
$url = "$symbols{GIT}/blob/$symbols{BRANCH}/$filename";
$url =~ s/ /%20/g;
$url =~ s/#/%23/g;
$url =~ s/\+/%2B/g;
if ($missing == 1) {
writeln ("//[*$url $_]//");
}
else {
writeln ("**[*$url $_]**");
$translations {$_} += 1;
}
}
$examples++;
writeln ('[[/collapsible]]');
writeln ('[[/>]]');
}
# Process plain code block
elsif (/\[\[code\]\]/) {
Expand All @@ -218,31 +180,38 @@ EOF
# Link to resource in git, nice way to upload images
writeln ("[[=image $symbols{GIT}/raw/$symbols{BRANCH}/images/fig$image.png]]");
}
elsif (/\[\[code/) {
print "E: unparsed code block: $_\n";
}
else {
# Normal text
writeln ($_);
}
}
print IMAGES "</html>\n";
close (IMAGES);
close (OUTPUT);

printf "||||||~ Translations ($examples in total)||\n";
die "Can't create scoreboard.wd: $!"
unless open (SCOREBOARD, ">scoreboard.wd");
print (SCOREBOARD "||||||~ Translations ($examples in total)||\n");
foreach (@languages) {
printf "|| %s || %3d || %3d%% ||\n", $_, $translations {$_}, ($translations {$_} * 100) / $examples;
printf (SCOREBOARD "|| %s || %3d || %3d%% ||\n", $_, $translations {$_}, ($translations {$_} * 100) / $examples);
}
close (SCOREBOARD);
print UPLOAD "wdput zguide main scoreboard \"Language scoreboard\"\n";

print "MAKE: $make_diagrams\n";
exit;

if ($make_diagrams == 1) {
system ("rm -f images/fig*");
system ("java -jar /usr/local/bin/ditaa0_9.jar images.html -o -h -E output.html");
# Need to trim twice for reasons I don't care to explore
system ("mogrify -trim images/fig*.png");
system ("mogrify -trim images/fig*.png");
system ("rm output.html");
}
print IMAGES "</html>\n";
close (IMAGES);
close (OUTPUT);
close (UPLOAD);

signatures_save ();

system ("rm -f images/fig*");
system ("java -jar bin/ditaa0_9.jar images.html -o -h -E output.html");
exit (1) if $?;
# Need to trim twice for reasons I don't care to explore
system ("mogrify -trim images/fig*.png");
system ("mogrify -trim images/fig*.png");
exit (1) if $?;
system ("rm output.html");
system ("rm images.html");

exit (0);
Expand All @@ -256,9 +225,99 @@ sub writeln {
print OUTPUT "$_\n" unless $EOD;
}

sub get_filename {
local ($name, $language) = @_; # Get arguments
return "examples/$language/$name.$extension{$language}";
# Process one example in one language

sub process_one_language {
local ($title, $name, $language, $show) = @_;
$filename = "examples/$language/$name.$extension{$language}";

# Create empty example if necessary
if (-f $filename) {
writeln ("[[collapsible show=\"$title in $language\" hide=\"$title in $language\"]]")
unless $show;
writeln ("[[include $extension{$language}:$name]]");
writeln ("[[/collapsible]]")
unless $show;
if (signature_changed ($filename)) {
print "Processing $name (in $language)...\n";
system ("echo \"[[html]]\">examples/$language/$name.wd");
system ("pygmentize -f html -O full $filename >>examples/$language/$name.wd");
exit (1) if $?;
system ("echo \"[[/html]]\">>examples/$language/$name.wd");
print UPLOAD "cd examples/$language\n";
print UPLOAD " wdput zguide $extension{$language} $name \"$title in $language\"\n";
print UPLOAD " rm $name.wd\n";
print UPLOAD "cd ../..\n";
signature_update ($filename);
}
return 1; # File exists
}
else {
$missing = "$missing, " if $missing;
$missing = "$missing$language";
return 0;
}
}


# Load signatures hash table
sub signatures_load {
print "I: loading signatures... ";
undef %signatures;
local $count = 0;
if (open (SIGNATURES, ".signatures")) {
while (<SIGNATURES>) {
/([^\s]+)\s+([^\s]+)/;
$signatures {$2} = $1;
$count++;
}
}
print "$count signatures loaded\n";
}

# If file signature has changed, return 1, else 0
sub signature_changed {
local ($filename) = @_;
$_ = `sha1sum $filename`;
if (/([^\s]+)\s+/) {
if ($signatures {$filename} eq $1) {
return 0;
}
else {
return 1;
}
}
else {
"E: can't sha1sum $filename\n";
return 0;
}
}

# Save file signature into table
sub signature_update {
local ($filename) = @_;
$_ = `sha1sum $filename`;
if (/([^\s]+)\s+/) {
$signatures {$filename} = $1;
}
else {
"E: can't sha1sum $filename\n";
return 0;
}
}

# Save signatures table
sub signatures_save {
print "I: saving signatures... ";
local $count = 0;
local $filename;
if (open (SIGNATURES, ">.signatures")) {
foreach $filename (keys %signatures) {
print SIGNATURES "$signatures{$filename} $filename\n";
$count++;
}
}
print "$count signatures saved\n";
}


Expand Down
Loading

0 comments on commit 518807b

Please sign in to comment.