zlax/ljr
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

init

Browse Source
This commit is contained in:
ivan
2019-02-06 00:49:12 +03:00
commit 8dbb1bb605
4796 changed files with 506072 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

320
livejournal/doc/raw/s2/lj/build.pl Executable file
View File

@@ -0,0 +1,320 @@
#!/usr/bin/perl
#
use strict;
use Getopt::Long;
my $XSL_VERSION_RECOMMENDED = "1.55.0";
my $opt_clean;
my ($opt_myxsl, $opt_getxsl, $opt_single);
exit 1 unless GetOptions('clean' => \$opt_clean,
'myxsl' => \$opt_myxsl,
'getxsl' => \$opt_getxsl,
'single' => \$opt_single,
);
my $home = $ENV{'LJHOME'};
require "$home/cgi-bin/ljlib.pl";
require "$home/cgi-bin/LJ/S2.pm";
$ENV{'SGML_CATALOG_FILES'} = $LJ::CATALOG_FILES || "/usr/share/sgml/docbook/dtd/xml/4.1/docbook.cat";
unless (-e $ENV{'SGML_CATALOG_FILES'}) {
die "Catalog files don't exist. Either set \$LJ::CATALOG_FILES, install docbook-xml (on Debian), or symlink $ENV{'SGML_CATALOG_FILES'} to XML DocBook 4.1's docbook.cat.";
}
if ($opt_getxsl) {
chdir "$home/doc/raw/build" or die "Where is build dir?";
unlink "xsl-docbook.tar.gz";
my $fetched = 0;
my $url = "http://www.livejournal.org/misc/xsl-docbook.tar.gz";
my @fetcher = ([ 'wget', "wget $url", ],
[ 'lynx', "lynx -source $url > xsl-docbook.tar.gz", ],
[ 'GET', "GET $url > xsl-docbook.tar.gz", ]);
foreach my $fet (@fetcher) {
next if $fetched;
print "Looking for $fet->[0] ...\n";
next unless `which $fet->[0]`;
print "RUNNING: $fet->[1]\n";
system($fet->[1])
and die "Error running $fet->[0]. Interrupted?\n";
$fetched = 1;
}
unless ($fetched) {
die "Couldn't find a program to download things from the web. I looked for:\n\t".
join(", ", map { $_->[0] } @fetcher) . "\n";
}
system("tar", "zxvf", "xsl-docbook.tar.gz")
and die "Error extracting xsl-doxbook.tar.gz; have GNU tar?\n";
}
my $output_dir = "$home/htdocs/doc/s2";
my $docraw_dir = "$home/doc/raw";
my $XSL = "$docraw_dir/build/xsl-docbook";
open (F, "$XSL/VERSION");
my $XSL_VERSION;
{
local $/ = undef; my $file = <F>;
$XSL_VERSION = $1 if $file =~ /VERSION.+\>(.+?)\</;
}
close F;
my $download;
if ($XSL_VERSION && $XSL_VERSION ne $XSL_VERSION_RECOMMENDED && ! $opt_myxsl) {
print "\nUntested DocBook XSL found at $XSL.\n";
print " Your version: $XSL_VERSION.\n";
print " Recommended: $XSL_VERSION_RECOMMENDED.\n\n";
print "Options at this point. Re-run with:\n";
print " --myxsl to proceed with yours, or\n";
print " --getxsl to install recommended XSL\n\n";
exit 1;
}
if (! $XSL_VERSION) {
print "\nDocBook XSL not found at $XSL.\n\nEither symlink that dir to the right ";
print "place (preferrably at version $XSL_VERSION_RECOMMENDED),\nor re-run with --getxsl ";
print "for me to do it for you.\n\n";
exit 1;
}
open(AUTOGEN, ">$docraw_dir/s2/lj/autogen-entities.xml") || die "Can't open autogen-entities.xml\n";
print AUTOGEN "<!ENTITY siteroot \"$LJ::SITEROOT\">\n";
close(AUTOGEN);
autogen_core();
mkdir $output_dir, 0755 unless -d $output_dir;
chdir $output_dir or die "Couldn't chdir to $output_dir\n";
my $cssparam;
if (-e "$docraw_dir/build/style.css") {
$cssparam = "--stringparam html.stylesheet style.css";
system("cp", "$docraw_dir/build/style.css", "$output_dir")
and die "Error copying stylesheet.\n";
}
system("xsltproc --nonet --catalogs $cssparam ".
"$docraw_dir/build/chunk.xsl $docraw_dir/s2/lj/index.xml")
and die "Error generating chunked HTML. (no xsltproc?)\n";
if ($opt_single)
{
system("xsltproc --nonet --catalogs --output manual.html $cssparam ".
"$docraw_dir/build/nochunk.xsl $docraw_dir/s2/lj/index.xml")
and die "Error generating single HTML. (no xsltproc?)\n";
}
sub autogen_core
{
my $cv = shift;
unless ($cv) {
autogen_core(1);
return;
}
my $pub = LJ::S2::get_public_layers();
my $id = $pub->{"core$cv"};
$id = $id ? $id->{'s2lid'} : 0;
die unless $id;
my $dbr = LJ::get_db_reader();
my $rv = S2::load_layers_from_db($dbr, $id);
my $s2info = S2::get_layer_all($id);
my $class = $s2info->{'class'} || {};
open (AC, ">$docraw_dir/s2/lj/autogen-core$cv.xml") or die "Can't open autogen-core$cv.xml\n";
my $xlink = sub {
my $r = shift;
$$r =~ s/\[class\[(\w+)\]\]/<link linkend=\"&s2.idroot;core$cv.class.$1\">$1<\/link>/g;
$$r =~ s/\[method\[(.+?)\]\]/<link linkend=\"&s2.idroot;core$cv.meth.$1\">$1<\/link>/g;
$$r =~ s/\[function\[(.+?)\]\]/<link linkend=\"&s2.idroot;core$cv.func.$1\">$1<\/link>/g;
$$r =~ s/\[member\[(.+?)\]\]/<link linkend=\"&s2.idroot;core$cv.member.$1\">$1<\/link>/g;
my @parts = split(/\s*\/\/\s*/, $$r);
if (@parts > 1) {
$$r = shift @parts;
my $see_also;
foreach my $p (@parts) {
if ($p =~ /^SeeAlso:\s*(.+)/) {
my $ids = $1;
my $str = " (See also: " . join(', ',
map { "<xref linkend='$_' />"; }
split(/\s*\,\s*/, $ids)) . ")";
$$r .= $str;
}
}
}
};
my $xlink_args = sub {
my $r = shift;
return unless
$$r =~ /^(.+?\()(.*)\)$/;
my ($new, @args) = ($1, split(/\s*\,\s*/, $2));
foreach (@args) {
s/^(\w+)/defined $class->{$1} ? "[class[$1]]" : $1/eg;
}
$new .= join(", ", @args) . ")";
$$r = $new;
$xlink->($r);
};
# layerinfo
#if (my $info = $s2info->{'info'}) {
# $body .= "<?h1 Layer Info h1?>";
# $body .= "<table class='postheading' style='margin-bottom: 10px' border='1' cellpadding='2'>";
# foreach my $k (sort keys %$info) {
# my ($ek, $ev) = map { LJ::ehtml($_) } ($k, $info->{$k});
# $title = $ev if $k eq "name";
# $body .= "<tr><td><b>$ek</b></td><td>$ev</td></tr>\n";
# }
# $body .= "</table>";
#}
# sets
if (my $prop = $s2info->{'prop'}) {
my $set = $s2info->{'set'};
print AC "<section id='&s2.idroot;core$cv.props'>\n";
print AC "<title>Properties</title>";
print AC "<variablelist>\n";
foreach my $pname (sort keys %$prop) {
my $prop = $prop->{$pname};
my $des = $prop->{'doc'} || $prop->{'des'};
$xlink->(\$des);
print AC "<varlistentry id='&s2.idroot;core$cv.prop.$pname'><term><varname>\$*$pname</varname> : <classname>$prop->{type}</classname></term>\n";
print AC "<listitem><para>$des</para></listitem>";
my $v = $set->{$pname};
if (defined $v) {
if (ref $v eq "HASH") {
if ($v->{'_type'} eq "Color") {
# FIXME: emit something we can turn into a colored box in DocBoox XSLT
$v = $v->{'as_string'};
} else {
$v = "[unknown object type]";
}
} elsif (ref $v eq "ARRAY") {
$v = "<emphasis>List:</emphasis> (" . join(", ", @$v) . ")";
}
print AC "<listitem><para><emphasis role='bold'>Base value:</emphasis> $v</para></listitem>\n";
}
print AC "</varlistentry>\n";
}
print AC "</variablelist>\n";
print AC "</section>\n";
}
# global functions
my $gb = $s2info->{'global'};
if (ref $gb eq "HASH" && %$gb) {
print AC "<section id='&s2.idroot;core$cv.funcs'>\n";
print AC "<title>Functions</title>";
print AC "<variablelist>\n";
foreach my $fname (sort keys %$gb) {
my $rt = $gb->{$fname}->{'returntype'};
if (defined $class->{$rt}) {
$rt = "[class[$rt]]";
}
$xlink->(\$rt);
my $ds = $gb->{$fname}->{'docstring'};
$xlink->(\$ds);
my $args = $gb->{$fname}->{'args'};
$xlink_args->(\$args);
my $idsig = $fname;
print AC "<varlistentry id='&s2.idroot;core$cv.func.$idsig'><term><function>$args</function> : $rt</term><listitem><para>$ds</para></listitem></varlistentry>\n";
}
print AC "</variablelist>\n";
print AC "</section>\n";
}
if (%$class)
{
print AC "<section id='&s2.idroot;core$cv.classes'>\n";
print AC " <title>Classes</title>\n";
foreach my $cname (sort { lc($a) cmp lc($b) } keys %$class) {
print AC "<refentry id='&s2.idroot;core$cv.class.$cname'>";
print AC "<refmeta><refentrytitle>$cname Class</refentrytitle></refmeta>";
my $ds = "<refnamediv><refname>$cname Class</refname><refpurpose>$class->{$cname}->{'docstring'}</refpurpose></refnamediv>";
if ($class->{$cname}->{'parent'}) {
$ds .= "<refsect1><title>Parent Class</title><para> Child class of [class[$class->{$cname}->{'parent'}]].</para></refsect1>";
}
my @children = grep { $class->{$_}->{'parent'} eq $cname } keys %$class;
if (@children) {
$ds .= "<refsect1><title>Derived Classes</title><para> Child classes: " .
join(", ", map { "[class[$_]]" } @children) . ".</para></refsect1>";
}
if ($ds) {
$xlink->(\$ds);
print AC $ds;
}
# build functions & methods
my (%func, %var);
my $add = sub {
my ($self, $aname) = @_;
foreach (keys %{$class->{$aname}->{'funcs'}}) {
$func{$_} = $class->{$aname}->{'funcs'}->{$_};
$func{$_}->{'_declclass'} = $aname;
}
foreach (keys %{$class->{$aname}->{'vars'}}) {
$var{$_} = $class->{$aname}->{'vars'}->{$_};
$var{$_}->{'_declclass'} = $aname;
}
my $parent = $class->{$aname}->{'parent'};
$self->($self, $parent) if $parent;
};
$add->($add, $cname);
print AC "<refsect1><title>Members</title><variablelist>" if %var;
foreach (sort keys %var) {
my $type = $var{$_}->{'type'};
$type =~ s/(\w+)/defined $class->{$1} ? "[class[$1]]" : $1/eg;
$xlink->(\$type);
my $ds = LJ::ehtml($var{$_}->{'docstring'});
$xlink->(\$ds);
if ($var{$_}->{'readonly'}) {
$ds = "<emphasis role='bold'>(Read-only)</emphasis> $ds";
}
print AC "<varlistentry id='&s2.idroot;core$cv.member.${cname}.$_'>";
print AC "<term><varname>$type $_</varname></term>";
print AC "<listitem><para>$ds</para></listitem></varlistentry>";
}
print AC "</variablelist></refsect1>" if %var;
print AC "<refsect1><title>Methods</title><variablelist>" if %func;
foreach (sort keys %func) {
my $rt = $func{$_}->{'returntype'};
if (defined $class->{$rt}) {
$rt = "[class[$rt]]";
}
$xlink->(\$rt);
my $ds = LJ::ehtml($func{$_}->{'docstring'});
$xlink->(\$ds);
my $args = $_;
$xlink_args->(\$args);
print AC "<varlistentry id='&s2.idroot;core$cv.meth.${cname}.$_'>";
print AC "<term><methodname>$args : $rt</methodname></term>";
print AC "<listitem><para>$ds</para></listitem></varlistentry>";
}
print AC "</variablelist></refsect1>" if %func;
print AC "</refentry>";
}
print AC "</section>";
}
close AC;
return;
}
__END__

191
livejournal/doc/raw/s2/lj/dateformats.xml Executable file
View File

@@ -0,0 +1,191 @@
<section id='&s2.idroot;siteapi.core1.dateformats'>
<title>Date Formats</title>
<para>The <function>Date</function> class has a method <function>date_format()</function> and its subclass <function>DateTime</function> adds the method <function>time_format()</function>. There's also a <function>month_format()</function> on objects dealing with only a month. All these methods take an optional format string which can be either a named format or a custom format string. If no format is provided, a default sensible version is used. The default is indicated in the table below.</para>
<section id='&s2.idroot;siteapi.core1.dateformat.named'>
<title>Named Date Formats</title>
<para>The following named date formats are supported and localized for internationalization. The English representation is shown only as an example.</para>
<informaltable frame='all'>
<tgroup cols='2' align='left' colsep='1' rowsep='1'>
<colspec align="left" />
<thead>
<row>
<entry>Method</entry>
<entry>Named Format</entry>
<entry>Default?</entry>
<entry>English Format</entry>
<entry>English Result</entry>
</row>
</thead>
<tbody>
<row>
<entry>date_format</entry>
<entry>short</entry>
<entry>X</entry>
<entry>%%m%%/%%d%%/%%yy%%</entry>
<entry>2/5/80</entry>
</row>
<row>
<entry>date_format</entry>
<entry>med</entry>
<entry></entry>
<entry>%%mon%%. %%dayord%%, %%yyyy%%</entry>
<entry>Feb. 5th, 1980</entry>
</row>
<row>
<entry>date_format</entry>
<entry>med_day</entry>
<entry></entry>
<entry>%%da%%, %%mon%%. %%dayord%%, %%yyyy%%</entry>
<entry>Tue, Feb. 5th, 1980</entry>
</row>
<row>
<entry>date_format</entry>
<entry>long</entry>
<entry></entry>
<entry>%%month%% %%dayord%%, %%yyyy%%</entry>
<entry>February 5th, 1980</entry>
</row>
<row>
<entry>date_format</entry>
<entry>long_day</entry>
<entry></entry>
<entry>%%day%%, %%month%% %%dayord%%, %%yyyy%%</entry>
<entry>Tuesday, February 5th, 1980</entry>
</row>
<row>
<entry>time_format</entry>
<entry>short</entry>
<entry>X</entry>
<entry>%%hh%%:%%min%% %%a%%m</entry>
<entry>12:34 am</entry>
</row>
<row>
<entry>month_format</entry>
<entry>short</entry>
<entry></entry>
<entry>%%m%%/%%yy%%</entry>
<entry>04/03</entry>
</row>
<row>
<entry>month_format</entry>
<entry>med</entry>
<entry></entry>
<entry>%%mon%% %%yyyy%%</entry>
<entry>Apr 2003</entry>
</row>
<row>
<entry>month_format</entry>
<entry>long</entry>
<entry>X</entry>
<entry>%%month%% %%yyyy%%</entry>
<entry>April 2003</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</section>
<section id='&s2.idroot;siteapi.core1.dateformat.custom'>
<title>Custom Date Formats</title>
<para>If you're making a style for yourself and don't care about keeping the date formats generic for internationalization, you can construct your own date format string with interpolated variables which you surround in double percent signs.</para>
<informaltable frame='all'>
<tgroup cols='2' align='left' colsep='1' rowsep='1'>
<colspec align="left" />
<thead>
<row>
<entry>Variable</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry>m</entry>
<entry>Month, 1-12.</entry>
</row>
<row>
<entry>mm</entry>
<entry>Month, 01-12.</entry>
</row>
<row>
<entry>d</entry>
<entry>Day, 1-31.</entry>
</row>
<row>
<entry>dd</entry>
<entry>Day, 01-31.</entry>
</row>
<row>
<entry>yy</entry>
<entry>Year, two digits.</entry>
</row>
<row>
<entry>yyyy</entry>
<entry>Year, four digits.</entry>
</row>
<row>
<entry>mon</entry>
<entry>Short month name, translated. (English: Jan, Feb, &hellip;)</entry>
</row>
<row>
<entry>month</entry>
<entry>Long month name, translated. (English: January, February, &hellip;)</entry>
</row>
<row>
<entry>da</entry>
<entry>Short day of week, translated. (English: Sun, Mon, &hellip;)</entry>
</row>
<row>
<entry>day</entry>
<entry>Long day of week, translated. (English: Sunday, Monday, &hellip;)</entry>
</row>
<row>
<entry>dayord</entry>
<entry>Ordinal day of month, translated. (English: 1st, 2nd, 3rd, &hellip;)</entry>
</row>
<row>
<entry>H</entry>
<entry>Hour, 0-23.</entry>
</row>
<row>
<entry>HH</entry>
<entry>Hour, 00-23.</entry>
</row>
<row>
<entry>h</entry>
<entry>Hour, 1-12.</entry>
</row>
<row>
<entry>hh</entry>
<entry>Hour, 01-12.</entry>
</row>
<row>
<entry>min</entry>
<entry>Minute, 00-59.</entry>
</row>
<row>
<entry>sec</entry>
<entry>Second, 00-59.</entry>
</row>
<row>
<entry>a</entry>
<entry>"a" for am, "p" for pm.</entry>
</row>
<row>
<entry>A</entry>
<entry>"A" for am, "P" for pm.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</section>
</section>

38
livejournal/doc/raw/s2/lj/entities.xml Executable file
View File

@@ -0,0 +1,38 @@
<!ENTITY s2.idroot "">
<!ENTITY s2.bookinfo SYSTEM "../bookinfo.xml">
<!ENTITY s2.preface SYSTEM "../preface.xml">
<!ENTITY s2.about SYSTEM "../about.xml">
<!ENTITY s2.history SYSTEM "../history.xml">
<!ENTITY s2.design SYSTEM "../design.xml">
<!ENTITY s2.overview SYSTEM "../overview.xml">
<!ENTITY s2.terms SYSTEM "../terms.xml">
<!ENTITY s2.layers SYSTEM "../layers.xml">
<!ENTITY s2.langref SYSTEM "../langref.xml">
<!ENTITY s2.notes SYSTEM "../notes.xml">
<!ENTITY s2.how SYSTEM "../how.xml">
<!ENTITY s2.caveats SYSTEM "../caveats.xml">
<!ENTITY s2.misc SYSTEM "../misc.xml">
<!ENTITY s2.csp SYSTEM "../csp.xml">
<!ENTITY s2.faq SYSTEM "../faq.xml">
<!ENTITY appx.gfdl SYSTEM "../appx.gfdl.xml">
<!-- LJ Specific Pages / Notes -->
<!ENTITY s2.quickstart SYSTEM "quickstart.xml">
<!ENTITY s2.s2onlj SYSTEM "s2onlj.xml">
<!ENTITY s2.faq.extra SYSTEM "faq.xml">
<!ENTITY s2.siteapi SYSTEM "siteapi.xml">
<!ENTITY s2.siteapi.core1.autogen SYSTEM "autogen-core1.xml">
<!ENTITY s2.siteapi.core1.dateformats SYSTEM "dateformats.xml">
<!-- Auto-generated include -->
<!ENTITY % autogen SYSTEM "autogen-entities.xml">
%autogen;

17
livejournal/doc/raw/s2/lj/faq.xml Executable file
View File

@@ -0,0 +1,17 @@
<qandaentry id='&s2.idroot;faq.s1tos2'>
<question><simpara>Will there be an S1 to S2 converter?</simpara></question>
<answer>
<para>Short answer: No.</para>
<para>Long answer: Maybe, but we're not going to help make it. The problem is that there's no proper way to convert an S1 style to S2. A converter could be made, with much pain, but it'd generate totally ugly S2 code which ignores all the benefits of S2. The resultant code would be so horrid that the potential migrator from S1 would see it, cry, and never come back to S2, the auto-converted code having left such a rotten taste in his or her mouth.</para>
<para>Actually, what we hope will happen is that somebody (or many people) will get inspired and start making new style languages <emphasis>on top of</emphasis> S2, many of which would likely be targetted at the HTML-hacker audience who want a style system more like S1.</para>
</answer>
</qandaentry>
<qandaentry id='&s2.idroot;faq.s2large'>
<question><simpara>Why is S2 so large/complex/difficult?</simpara></question>
<answer>
<para>It's not, really. You're probably just overwhelmed and frustrated, hoping it was like S1 with more support for certain pages. Unfortunately, S1 was a dead-end and couldn't be usefully extended.</para>
<para>S2 has more than you'll ever use, but that's not to say the rest of it is a waste. Just because you only speak English, does that mean we shouldn't address the problem of internationalization?</para>
<para>S2's been designed to be as easy as possible on both regular users and programmers. Once you start creating/modifying S2 code, you should find it's not so bad. And once you have a wild idea of something you want to do with your style, it'll actually be possible... just consult the S2 core layer reference and figure out how to get what you're looking for.</para>
<para>Also, see the last paragraph to the previous question.</para>
</answer>
</qandaentry>

32
livejournal/doc/raw/s2/lj/index.xml Executable file
View File

@@ -0,0 +1,32 @@
<?xml version="1.0"?>
<!DOCTYPE book SYSTEM "/usr/share/sgml/docbook/dtd/xml/4.1.2/docbookx.dtd" [
<!ENTITY % content SYSTEM "entities.xml">
%content;
]>
<book id="index" status="prelim" lang="en">
&s2.bookinfo;
<chapter id='&s2.idroot;intro'>
&s2.preface;
</chapter>
&s2.quickstart;
<chapter id='&s2.idroot;overview'>
&s2.overview;
</chapter>
<chapter id='&s2.idroot;langref'>
&s2.langref;
</chapter>
<chapter id='&s2.idroot;notes'>
&s2.notes;
</chapter>
<chapter id='&s2.idroot;csp'>
&s2.csp;
</chapter>
&s2.s2onlj;
<appendix id='&s2.idroot;siteapi'>
&s2.siteapi;
</appendix>
<appendix id='&s2.idroot;faq'>
&s2.faq;
</appendix>
&appx.gfdl;
</book>

277
livejournal/doc/raw/s2/lj/quickstart.xml Executable file
View File

@@ -0,0 +1,277 @@
<chapter id='&s2.idroot;quickstart'>
<title>Quick Start Guide</title>
<subtitle>Quick Start Guide to using S2 on LiveJournal</subtitle>
<abstract>
<para>
Widely considered a myth by many users of LiveJournal.com, S2 is the
long-awaited new style system for LiveJournal. In four years of use,
the original LiveJournal style system has allowed LiveJournal users
to create truly unique layouts for their journals, but shown many
limitations due to things not considered during its initial design.
Some functionality has been cobbled on as an afterthought, and this
has left the style system clunky and restrictive, with some ugly
kludges which noone really likes.
</para>
<para>
S2 was conceived to remove all limitations and make LiveJournal
truly customizable in almost any conceivable way. Redesigned from
the ground up, S2 is completely different from the old style system,
but introduces new functionality and makes it easier to create a
complimentary set of journal views. It also adds new views, including
customized comment views and, in the future, photo gallery, memory,
and user information views.
</para>
</abstract>
<section id='&s2.idroot;quickstart.intro'>
<title>Getting to know S2</title>
<section id='&s2.idroot;quickstart.intro.terms'>
<title>Common Terms</title>
<variablelist>
<title>General Terms</title>
<varlistentry>
<term>Journal View</term>
<listitem>
<simpara>
A journal view is the name for the different parts of a
LiveJournal account which a user can create or customize a layout for.
Someone's journal itself is called the <quote>Recent</quote> view,
meaning that it shows all of that user's recent entries. The most
popular view is the <quote>Friends</quote> view, with which a user
can read all of their <quote>friends'</quote> updates.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>Layers</term>
<listitem>
<simpara>
S2 uses the concept of <quote>layers</quote> to provide different levels
of customization - each layer in a style deals with a different aspect of the
style, ranging from color to translation to HTML options and settings. A
complete style is the result of putting its different layers together for use.
</simpara>
</listitem>
</varlistentry>
</variablelist>
<variablelist>
<title>Style Layers</title>
<varlistentry>
<term>Core</term>
<listitem>
<simpara>
The core layer is the foundation of all styles. The core layer
defines all of the functions and classes available to the lower
layers. The core layer itself is fully functional as well;
someone could use just the core definitions for each journal view
to create a working (yet rather bland) style. The core layer is mostly
just a base to work from, a guide to help form a complete style that
helps by patching holes where necessary.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>Core - Internationalization</term>
<listitem>
<simpara>
The core internationalization layer provides all of the text information
to help display someone's journal in a different language. This layer,
like the core layer, is only really a base or a guide to create new
internationalization layers from.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>Layout</term>
<listitem>
<simpara>
A layout layer is where the real customization starts. To draw a loose
comparison to the old style system, a layout layer can be regarded as an
S1 style except that the S2 layout covers each journal view, unlike the
s1 style that only dealt with a single view. A layout layer, much like the core
layer, defines its own set of properties that change the appearance and
behavior of the layout.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>Internationalization</term>
<listitem>
<simpara>
An internationalization layer provides all of the text information
that pertains to a specific layout layer, so that users can select
which language their journal should display in. A complete style uses
text from both an internationalization layer and the core internationalization
layer.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>Theme</term>
<listitem>
<simpara>
A theme layer uses the color properties available in a layout layer to create
a unique look for the style. To draw another loose comparison to the old style
system, a theme layer is much like a color theme, except that a theme is only
unique to one layout, unlike its S1 counterpart, which only worked for all styles.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>User</term>
<listitem>
<simpara>
A user layer is the final layer where most people's options will be set. Few people
will create a user layer by hand, because a user layer is mostly handled by the customization
wizards. To draw a final comparison to the old style system, you can think of a user
layer as the equivalent to the <guilabel>Overrides</guilabel> box for S1, except there is
a lot less headache involved in creating a user layer.
</simpara>
</listitem>
</varlistentry>
</variablelist>
</section>
<!-- Explain how styles are built when requested, basically
<section id='&s2.idroot;quickstart.intro.how'>
<title>How it works</title>
</section>
-->
</section>
<section id='&s2.idroot;quickstart.use'>
<sectioninfo>
<authorgroup>
<author><firstname>Melissa</firstname><surname>Della</surname></author>
<editor><firstname>Jesse</firstname><surname>Proulx</surname></editor>
</authorgroup>
</sectioninfo>
<title>Configuring your account to use S2</title>
<para>
To start using S2, you'll need to turn S2 on for your account. Go to
<ulink url='&siteroot;/customize/' />, make sure the appropriate account
is selected (if you control more than one account from the one you're
logged into), and choose <guilabel>New System (S2)</guilabel> from the
drop-down menu. Now save your changes (click <guibutton>Change</guibutton>).
<tip>
<simpara>
You can always switch back to S1; all of your S1 styles and overrides
are kept intact.
</simpara>
</tip>
</para>
<para>
In this section, we'll go through the use of wizards. They are relatively
self-explanitory by design, so this will only breifly take you through
the steps.
</para>
<procedure><title>Selecting a Style</title>
<step>
<para>
The first step is to choose a layout. You'll notice most of the S1 system
styles have been ported to S2. For example purposes we'll use the default
style, Generator. This should already be selected, if you haven't done
any tweaking prior to reading this guide. Next to the <guibutton>Change</guibutton>
button there is a link for layout previews. If you wish to see examples of
other styles you may use, open this page in a new window and peruse.
</para>
</step>
<step>
<para>
Again, for example purposes, and because we're assuming that english is your primary language,
select <quote>English</quote> in the language section.
</para>
</step>
<step>
<para>
Next you can choose a theme for your layout. Themes are basically just
default sets of colors that we've chosen to help you start customizing your journal.
You can preview each theme by selecting the <guilabel>(previews)</guilabel> link,
located next to the <guibutton>Change</guibutton> button. If no color themes are to your liking,
you can override any color by creating a new user layer, which we'll explain how to
do next.
</para>
</step>
<step>
<para>
Now that you've chosen a style, a language, and a color theme, you can
begin creating a custom user layer by clicking the <guibutton>Customize&hellip;</guibutton>
button at the bottom of the page.
</para>
</step>
</procedure>
<procedure><title>Creating a user layer</title>
<step>
<para>
On the Customize page, the first set of options is devoted to tweaking all of the
available colors from the style you've chosen. For brevity purposes we'll only
change two colors (feel free to change more as you see fit).
</para>
<para>
Assuming you've chosen the Generator style, scroll down to the <guilabel>Page background color
(and around userpics)</guilabel> option and select the
<guibutton>Override</guibutton> button; from here you can press <guibutton>Choose</guibutton>
for a pop-up color selector, or you can simply enter the hexadecimal color code if you know it.
For demonstration purposes you can simply type <userinput>#cef5c1</userinput> in the given box.
Scroll down to the <guilabel>Background color for the bar below entries</guilabel> option,
select <guibutton>Override</guibutton>, and enter the following hex code:
<userinput>#f1fded</userinput>. If you have JavaScript enabled in your browser, you'll see the
color previews dynamically change when you click outside of the option box.
</para>
</step>
<step>
<para>
Now that a couple of colors have changed, scroll down to the <guilabel>Box width (pixels)</guilabel>
option. Select <guibutton>Override</guibutton> and enter the value <literal>400</literal>.
</para>
</step>
<step>
<para>
Move to the next section labelled <guilabel>Link text to leave a comment</guilabel>, select
<guibutton>Override</guibutton>, and enter <literal>Post a new comment</literal>. For the next
option, <guilabel>Link text to read comment</guilabel>, select <guibutton>Override</guibutton>
and enter <literal>A single, lonely comment // Its a party in here with # people!</literal>.
Enter these same values for the friends view entry comment links.
</para>
</step>
<step>
<para>
Click on the <guibutton>Save</guibutton> button when you've completed the steps above. Now,
view your journal. Notice th colors, the width, and the comment links.
</para>
</step>
</procedure>
</section>
<section id='&s2.idroot;quickstart.moreinfo'>
<title>Where to go from here</title>
<variablelist>
<varlistentry>
<term><xref linkend='&s2.idroot;index' /></term>
<listitem><simpara>
We've made a manual available that covers every topic related to using S2 on LiveJournal. As a
matter of fact you're currently reading a chapter from the manual. To start from the beginning,
navigate to <xref linkend='&s2.idroot;index' />.
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><ulink url='http://www.livejournal.com/community/lj_style/info'>LJ Style Discussion</ulink></term>
<listitem><simpara>
<ulink url='http://www.livejournal.com/community/lj_style/info'>LJ Style Discussion</ulink> is a community
on <ulink url='http://www.livejournal.com/'>LiveJournal.com</ulink> that covers most S1 and S2 discussions.
This community has been sanctioned by administrators of LiveJournal as an <quote>official</quote> community.
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><ulink url='http://www.livejournal.com/community/s2practice/info'>S2 Practice Discussion</ulink></term>
<listitem><simpara>
<ulink url='http://www.livejournal.com/community/s2practice/info'>S2 Practice Discussion</ulink> is a community
on <ulink url='http://www.livejournal.com/'>LiveJournal.com</ulink> that deals with introducing S2 to
members of LiveJournal's support team. The introductory text available in the community was actually used
to write portions of this chapter.
</simpara></listitem>
</varlistentry>
</variablelist>
</section>
</chapter>

204
livejournal/doc/raw/s2/lj/s2onlj.xml Executable file
View File

@@ -0,0 +1,204 @@
<chapter id='&s2.idroot;s2onlj'>
<title>Using S2 on LiveJournal</title>
<section id='&s2.idroot;s2onlj.resources'>
<title>Resources</title>
<para><variablelist>
<varlistentry>
<term><ulink url="&siteroot;/customize/">Customization area</ulink></term>
<listitem><simpara>Regular end-user destination to select layouts and corresponding themes with
pretty graphical previews, and graphical wizard to override text/colors.</simpara></listitem>
</varlistentry>
<varlistentry>
<term><ulink url="&siteroot;/customize/advanced/">Advanced area</ulink></term>
<listitem><simpara>Create styles &amp; layers. View the S2 source and documentation page of any
public layer, notably the core layer and all the classes, functions and properties it provides.
</simpara></listitem>
</varlistentry>
</variablelist></para>
</section>
<section id='&s2.idroot;s2onlj.layerguide'>
<title>Layer Guidelines</title>
<para>This section is a list of suggestions for making good layers for LiveJournal, and also forms
the requirements for creating layers to be offered as standard by LiveJournal. You should read
this if you're designing a LiveJournal layout, or if you're writing the code to implement
a layout designed by someone else, or if you're just interested.</para>
<para>It seems that most people start creation of a layout by creating a static HTML mockup of
roughly what the layout will include. With this in mind, the guide is separated into two parts,
the first for those creating a design, and the second for those who are implementing a design
in S2 code. You might, of course, be both!</para>
<section id='&s2.idroot;s2onlj.layerguide.design'>
<title>Guidelines For Layout Designers</title>
<para>When starting to design a layout, you should keep in mind the following points.</para>
<itemizedlist>
<listitem>
<formalpara>
<title>Beware Copyright</title>
<para>Practically everything creative is copyrighted, from images to site designs
to program code. If you copy or clone someone else's design or HTML, or use an
image created by someone else, you may find yourself in a copyright lawsuit.
Also, any style which is to be part of the LiveJournal system must be distributable
under the GNU General Public Licence (GPL) under which the LiveJournal source
distribution is licenced. The easiest way to keep to this is to only use your
own work in creating a layer.</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title>Design Flexibly</title>
<para>S2 is designed to be extensible, and if you think about extensibility
early on your will make it much easier to adapt to suit additions to LiveJournal
later on.</para>
</formalpara>
<para>Some particular things to bear in mind are:
<itemizedlist>
<listitem><simpara>Try to allow for new view types to be added in future.
If you've got a list of views (Recent Entries, Friends etc) then
will it be easy to add more views to it later on without breaking
the design?</simpara></listitem>
<listitem><simpara>Try to keep the <quote>global</quote> HTML distinct
from the view-specific HTML. That is, decide what is part of the
recent view and what will be present on all views. Try to avoid
the view-specific HTML depending on the global HTML if you can.</simpara></listitem>
</itemizedlist>
</para>
</listitem>
<listitem>
<formalpara>
<title>Design for standard page elements</title>
<para>There are certain things which users expect to find in LiveJournal
styles. These include:
<itemizedlist>
<listitem><simpara>Links from the archive calendar view to see the
month view for each month shown.</simpara></listitem>
<listitem><simpara>A way to easily obtain <quote>permalink</quote> for each entry
which can be used to link to the entry. The S2 system will provide
the URL for this, but you need to decide where to put it.</simpara></listitem>
<listitem><simpara>Links on the Recent Entries and Friends views to
navigate to older entries and back to newer entries.</simpara></listitem>
<listitem><simpara>Links on a day page to view the previous and next day.</simpara></listitem>
<listitem><simpara>Links on the Archive calendar to view other years.</simpara></listitem>
<listitem><simpara>Titles and subtitles. The system allows the user
to give their journal a title and a subtitle, as well as a special
title for their friends view. You should display at least the main
titles as headings, and try to include the subtitle at least on
the Recent Entries view.</simpara></listitem>
</itemizedlist>
</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title>Design for Customization</title>
<para>As you are creating your design, try to think of things that users
might want to customize. Colors are the easiest to think of, but
you could also provide options for margin sizes, the position of
navigation bars and chosing classes of fonts.</para>
</formalpara>
<para>A gotcha with customization is that it can make it hard to incorporate
images into a style, since colors and alignments can change. If you are
writing a potential system layout, the system can provide dynamic image
color changes for your style in certain cases, but try to avoid this if
you can.</para>
</listitem>
<listitem>
<formalpara>
<title>Design for Internationalization</title>
<para>If you are designing a layout you should try to allow for
the text in your layout to be translated. A lot of commonly-used text
is already provided by the system translated, and it will be a lot
easier to make your style multi-lingual if you make use of the
standard text.</para>
</formalpara>
<para>One example is comment links on entries. The system provides functions
to create the comment links with text set in an internationalization layer,
including the correct pluralization for the comment count. If you design
such that any text could be used in your comment links (and anywhere else where
text appears, for that matter) your layout will be easily translatable.</para>
<para>Another thing to avoid is including text in images, as this is practically
impossible to translate flexibly.</para>
</listitem>
</itemizedlist>
</section>
<section id='&s2.idroot;s2onlj.layerguide.implementation'>
<title>Guidelines For Implementors</title>
<para>If you are a programmer writing the S2 code for an S2 layout (or, to a lesser extent,
some other layer) then this section is for you.</para>
<itemizedlist>
<listitem>
<formalpara>
<title>Use Properties</title>
<para>If you expose properties from your layout, the end-user will be able
to customize these properties from a web-based GUI interface. In general,
the more of these you have the better, but don't go overboard.</para>
</formalpara>
<itemizedlist>
<listitem><simpara>Colors are the main customizable feature of most layouts.
Try to allow the user to change the color of all major page elements, but
also dynamically generate similar colors based on user-supplied properties using
the methods of the <classname>Color</classname> class to lighten, darken,
invert or average.</simpara></listitem>
<listitem>
<simpara>Font selection is supported by the core layer, but you'll
have to explicitly state that you wish to expose these properties in your
layout. (See documentation on properties)</simpara>
<simpara>The core layer provides options to select a primary font family
as well as a fallback CSS generic font family, and one or both of
these can be ommitted. You should generate a sensible CSS font-family
property rule or equivalent FONT FACE value from these two properties.</simpara>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<formalpara>
<title>Let the System Help You</title>
<para>The core layer has lots of useful default implementations of various
page features. For example, it can generate
links to users and form page titles and subtitles from the relevant
user settings and translation properties. Using these defaults can save
you a lot of work.</para>
</formalpara>
<para>
The system also has several features to help layouts be expandable
without modifying a layout at all:
<itemizedlist>
<listitem><simpara>You can generate a list of views by iterating over
the <varname>views_order</varname> member of <classname>Page</classname>,
and if new top-level views are added in future, or if the URL to
one changes, your layout will automatically reflect the change.</simpara></listitem>
<listitem><simpara>The <quote>body</quote> of each view is separated from the
navigation and layout around it, so that if you make sure you
separate the view-specific code from the global code, new views
can be added in future and the default HTML generated by the core
layer will be used until the layout is revised to provide customized
output.</simpara></listitem>
</itemizedlist>
</para>
</listitem>
<listitem>
<formalpara>
<title>Text Abstraction</title>
<para>All text in a layout should be easily overridable either by properties
or by functions. Functions are required when text includes a number which
affects the grammar of a sentence, such <quote>You are viewing the 10 most recent
entries</quote>.
</para>
</formalpara>
<para>Don't break up sentences when allowing sentences to be changed, as sentence
construction differs wildly between languages.</para>
<para>Finally, check to see if the text you need is already provided by a function in
the core layer, as this will not only save you effort, but also save the effort of
anyone who tries to create internationalization layers for your layout. The core
layer provides functions and properties which are useful in practically all layouts,
including text for comment links and view names.</para>
</listitem>
</itemizedlist>
</section>
</section>
</chapter>

9
livejournal/doc/raw/s2/lj/siteapi.xml Executable file
View File

@@ -0,0 +1,9 @@
<title>LiveJournal's S2 API</title>
<para>S2 is a generic system which sites like LiveJournal can use. This appendix documents the LiveJournal-specific core layers, which provide the basic functionality that's available to all other layers. At present there's only one core layer (version 1), but in the future there may be more.</para>
<section id='&s2.idroot;siteapi.core1'>
<title>Core Layer 1</title>
<para>LiveJournal's only core layer, at present.</para>
&s2.siteapi.core1.autogen;
&s2.siteapi.core1.dateformats;
</section>