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

47
wcmtools/s2/doc/database.txt Executable file
View File

@@ -0,0 +1,47 @@
CREATE TABLE s2layers
(
s2lid INT UNSIGNED NOT NULL AUTO_INCREMENT,
PRIMARY KEY (s2lid),
b2lid INT UNSIGNED NOT NULL,
userid INT UNSIGNED NOT NULL,
type ENUM('core','i18nc','layout','theme','i18n','user') NOT NULL,
INDEX (userid),
INDEX (b2lid, type)
);
/* clustered */
CREATE TABLE s2style
(
userid INT UNSIGNED NOT NULL,
type ENUM('core','i18nc','layout','theme','i18n','user') NOT NULL,
UNIQUE (userid, type),
s2lid INT UNSIGNED NOT NULL
);
/* clustered */
CREATE TABLE s2info
(
s2lid INT UNSIGNED NOT NULL,
infokey VARCHAR(80) NOT NULL,
value VARCHAR(255) NOT NULL,
PRIMARY KEY (s2lid, infokey)
);
/* clustered */
CREATE TABLE s2source
(
s2lid INT UNSIGNED NOT NULL,
PRIMARY KEY (s2lid),
s2code MEDIUMBLOB
);
/* clustered */
CREATE TABLE s2compiled
(
s2lid INT UNSIGNED NOT NULL,
PRIMARY KEY (s2lid),
comptime INT UNSIGNED NOT NULL,
compdata MEDIUMBLOB
);

58
wcmtools/s2/doc/design_goals.txt Executable file
View File

@@ -0,0 +1,58 @@
Design Goals of S2:
===================
S2, or "LiveJournal, Style System, version 2", was designed with the
following goals in mind:
Easy and flexible for beginners:
End users that aren't programmers will be able to have an extreme
amount of control over their journals without ever editing text
in a large <textarea> box, like "S1". Because the new style
system layers reflect their properties, a series of wizards will
let users customize the appearance at a very high level.
Powerful and familiar for experts:
The new style system is actually a programming language, with
syntax and semantics resembling Perl/C+/Java/etc. The object
oriented & inheritance-based design of S2 is actually what leads
to the simplicity and flexibility for beginners. They won't need
to understand OO-design to benefit from the power that
customizing the function to dump a journal entry effects all the
different journal views. In fact, they'll probably not even
modify the function themselves--- they'll most likely redefine a
property using a web GUI that the style they're using recognizes
and respects accordingly.
Speed:
S2 code is compiled into a lower level language and run directly
when the page is loaded. Currently this lower level language is
Perl, but there is no reason the backend can't be any language.
Further, style layers are cached in a LRU pool by the web-server
to prevent unnecessary database access and re-compliation of the
resultant Perl code into Perl bytecodes. (the functions of a
style layer are stored as CODE refs in memory, ready to be run as
necessary... don't need to |eval| huge chunks of text each time)
Also, no buffering in memory of the resultant page is necessary
as in S1 ... each function in a layer can output directly to the
client, since the system isn't based on repeated substitutions as
in S1.
Security:
Rather than letting users program directly in C or Perl, S2
ensures that the resultant compiled code is both safe and fast.
The language isn't Turing complete, but by limiting the
functionality of the language we can ensure the program will
halt. Giving users an XML tree of data and letting them use XSLT
was one consideration, but XSLT is ugly and though some people
know it, it isn't as easy to pick up quickly as S2 is. Of
course, security wasn't the only design consideration, otherwise
we could've used Perl's Safe.pm module and let users run
restricted Perl with an alarm set to interrupt the code after a
number of seconds. S2 is a lot more encompassing. Security is
actually the easiest thing to guarantee once you built a whole
system like this.

3
wcmtools/s2/doc/docbook/about.xml Executable file
View File

@@ -0,0 +1,3 @@
<title>About S2</title>
<para>S2 is a generic style system which web applications can use to give both ordinary users and programmers extreme control over the look of their content.</para>
<para>S2 is currently in use by both the LiveJournal and FotoBilder codebases to produce the content of journals and photo albums, respectively.</para>

411
wcmtools/s2/doc/docbook/appx.gfdl.xml Executable file
View File

@@ -0,0 +1,411 @@
<appendix id="appx.gfdl">
<title>GNU Free Documentation License</title>
<!-- - GNU Project - Free Software Foundation (FSF) -->
<!-- LINK REV="made" HREF="mailto:webmasters@gnu.org" -->
<!-- sect1>
<title>GNU Free Documentation License</title -->
<para>Version 1.2, November 2002</para>
<blockquote>
<para> Copyright (C) 2000,2001,2002 Free Software Foundation, Inc.
59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.</para>
</blockquote>
<literallayout class="monospaced"><![CDATA[
0. PREAMBLE
The purpose of this License is to make a manual, textbook, or other
functional and useful document "free" in the sense of freedom: to
assure everyone the effective freedom to copy and redistribute it,
with or without modifying it, either commercially or noncommercially.
Secondarily, this License preserves for the author and publisher a way
to get credit for their work, while not being considered responsible
for modifications made by others.
This License is a kind of "copyleft", which means that derivative
works of the document must themselves be free in the same sense. It
complements the GNU General Public License, which is a copyleft
license designed for free software.
We have designed this License in order to use it for manuals for free
software, because free software needs free documentation: a free
program should come with manuals providing the same freedoms that the
software does. But this License is not limited to software manuals;
it can be used for any textual work, regardless of subject matter or
whether it is published as a printed book. We recommend this License
principally for works whose purpose is instruction or reference.
1. APPLICABILITY AND DEFINITIONS
This License applies to any manual or other work, in any medium, that
contains a notice placed by the copyright holder saying it can be
distributed under the terms of this License. Such a notice grants a
world-wide, royalty-free license, unlimited in duration, to use that
work under the conditions stated herein. The "Document", below,
refers to any such manual or work. Any member of the public is a
licensee, and is addressed as "you". You accept the license if you
copy, modify or distribute the work in a way requiring permission
under copyright law.
A "Modified Version" of the Document means any work containing the
Document or a portion of it, either copied verbatim, or with
modifications and/or translated into another language.
A "Secondary Section" is a named appendix or a front-matter section of
the Document that deals exclusively with the relationship of the
publishers or authors of the Document to the Document's overall subject
(or to related matters) and contains nothing that could fall directly
within that overall subject. (Thus, if the Document is in part a
textbook of mathematics, a Secondary Section may not explain any
mathematics.) The relationship could be a matter of historical
connection with the subject or with related matters, or of legal,
commercial, philosophical, ethical or political position regarding
them.
The "Invariant Sections" are certain Secondary Sections whose titles
are designated, as being those of Invariant Sections, in the notice
that says that the Document is released under this License. If a
section does not fit the above definition of Secondary then it is not
allowed to be designated as Invariant. The Document may contain zero
Invariant Sections. If the Document does not identify any Invariant
Sections then there are none.
The "Cover Texts" are certain short passages of text that are listed,
as Front-Cover Texts or Back-Cover Texts, in the notice that says that
the Document is released under this License. A Front-Cover Text may
be at most 5 words, and a Back-Cover Text may be at most 25 words.
A "Transparent" copy of the Document means a machine-readable copy,
represented in a format whose specification is available to the
general public, that is suitable for revising the document
straightforwardly with generic text editors or (for images composed of
pixels) generic paint programs or (for drawings) some widely available
drawing editor, and that is suitable for input to text formatters or
for automatic translation to a variety of formats suitable for input
to text formatters. A copy made in an otherwise Transparent file
format whose markup, or absence of markup, has been arranged to thwart
or discourage subsequent modification by readers is not Transparent.
An image format is not Transparent if used for any substantial amount
of text. A copy that is not "Transparent" is called "Opaque".
Examples of suitable formats for Transparent copies include plain
ASCII without markup, Texinfo input format, LaTeX input format, SGML
or XML using a publicly available DTD, and standard-conforming simple
HTML, PostScript or PDF designed for human modification. Examples of
transparent image formats include PNG, XCF and JPG. Opaque formats
include proprietary formats that can be read and edited only by
proprietary word processors, SGML or XML for which the DTD and/or
processing tools are not generally available, and the
machine-generated HTML, PostScript or PDF produced by some word
processors for output purposes only.
The "Title Page" means, for a printed book, the title page itself,
plus such following pages as are needed to hold, legibly, the material
this License requires to appear in the title page. For works in
formats which do not have any title page as such, "Title Page" means
the text near the most prominent appearance of the work's title,
preceding the beginning of the body of the text.
A section "Entitled XYZ" means a named subunit of the Document whose
title either is precisely XYZ or contains XYZ in parentheses following
text that translates XYZ in another language. (Here XYZ stands for a
specific section name mentioned below, such as "Acknowledgements",
"Dedications", "Endorsements", or "History".) To "Preserve the Title"
of such a section when you modify the Document means that it remains a
section "Entitled XYZ" according to this definition.
The Document may include Warranty Disclaimers next to the notice which
states that this License applies to the Document. These Warranty
Disclaimers are considered to be included by reference in this
License, but only as regards disclaiming warranties: any other
implication that these Warranty Disclaimers may have is void and has
no effect on the meaning of this License.
2. VERBATIM COPYING
You may copy and distribute the Document in any medium, either
commercially or noncommercially, provided that this License, the
copyright notices, and the license notice saying this License applies
to the Document are reproduced in all copies, and that you add no other
conditions whatsoever to those of this License. You may not use
technical measures to obstruct or control the reading or further
copying of the copies you make or distribute. However, you may accept
compensation in exchange for copies. If you distribute a large enough
number of copies you must also follow the conditions in section 3.
You may also lend copies, under the same conditions stated above, and
you may publicly display copies.
3. COPYING IN QUANTITY
If you publish printed copies (or copies in media that commonly have
printed covers) of the Document, numbering more than 100, and the
Document's license notice requires Cover Texts, you must enclose the
copies in covers that carry, clearly and legibly, all these Cover
Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
the back cover. Both covers must also clearly and legibly identify
you as the publisher of these copies. The front cover must present
the full title with all words of the title equally prominent and
visible. You may add other material on the covers in addition.
Copying with changes limited to the covers, as long as they preserve
the title of the Document and satisfy these conditions, can be treated
as verbatim copying in other respects.
If the required texts for either cover are too voluminous to fit
legibly, you should put the first ones listed (as many as fit
reasonably) on the actual cover, and continue the rest onto adjacent
pages.
If you publish or distribute Opaque copies of the Document numbering
more than 100, you must either include a machine-readable Transparent
copy along with each Opaque copy, or state in or with each Opaque copy
a computer-network location from which the general network-using
public has access to download using public-standard network protocols
a complete Transparent copy of the Document, free of added material.
If you use the latter option, you must take reasonably prudent steps,
when you begin distribution of Opaque copies in quantity, to ensure
that this Transparent copy will remain thus accessible at the stated
location until at least one year after the last time you distribute an
Opaque copy (directly or through your agents or retailers) of that
edition to the public.
It is requested, but not required, that you contact the authors of the
Document well before redistributing any large number of copies, to give
them a chance to provide you with an updated version of the Document.
4. MODIFICATIONS
You may copy and distribute a Modified Version of the Document under
the conditions of sections 2 and 3 above, provided that you release
the Modified Version under precisely this License, with the Modified
Version filling the role of the Document, thus licensing distribution
and modification of the Modified Version to whoever possesses a copy
of it. In addition, you must do these things in the Modified Version:
A. Use in the Title Page (and on the covers, if any) a title distinct
from that of the Document, and from those of previous versions
(which should, if there were any, be listed in the History section
of the Document). You may use the same title as a previous version
if the original publisher of that version gives permission.
B. List on the Title Page, as authors, one or more persons or entities
responsible for authorship of the modifications in the Modified
Version, together with at least five of the principal authors of the
Document (all of its principal authors, if it has fewer than five),
unless they release you from this requirement.
C. State on the Title page the name of the publisher of the
Modified Version, as the publisher.
D. Preserve all the copyright notices of the Document.
E. Add an appropriate copyright notice for your modifications
adjacent to the other copyright notices.
F. Include, immediately after the copyright notices, a license notice
giving the public permission to use the Modified Version under the
terms of this License, in the form shown in the Addendum below.
G. Preserve in that license notice the full lists of Invariant Sections
and required Cover Texts given in the Document's license notice.
H. Include an unaltered copy of this License.
I. Preserve the section Entitled "History", Preserve its Title, and add
to it an item stating at least the title, year, new authors, and
publisher of the Modified Version as given on the Title Page. If
there is no section Entitled "History" in the Document, create one
stating the title, year, authors, and publisher of the Document as
given on its Title Page, then add an item describing the Modified
Version as stated in the previous sentence.
J. Preserve the network location, if any, given in the Document for
public access to a Transparent copy of the Document, and likewise
the network locations given in the Document for previous versions
it was based on. These may be placed in the "History" section.
You may omit a network location for a work that was published at
least four years before the Document itself, or if the original
publisher of the version it refers to gives permission.
K. For any section Entitled "Acknowledgements" or "Dedications",
Preserve the Title of the section, and preserve in the section all
the substance and tone of each of the contributor acknowledgements
and/or dedications given therein.
L. Preserve all the Invariant Sections of the Document,
unaltered in their text and in their titles. Section numbers
or the equivalent are not considered part of the section titles.
M. Delete any section Entitled "Endorsements". Such a section
may not be included in the Modified Version.
N. Do not retitle any existing section to be Entitled "Endorsements"
or to conflict in title with any Invariant Section.
O. Preserve any Warranty Disclaimers.
If the Modified Version includes new front-matter sections or
appendices that qualify as Secondary Sections and contain no material
copied from the Document, you may at your option designate some or all
of these sections as invariant. To do this, add their titles to the
list of Invariant Sections in the Modified Version's license notice.
These titles must be distinct from any other section titles.
You may add a section Entitled "Endorsements", provided it contains
nothing but endorsements of your Modified Version by various
parties--for example, statements of peer review or that the text has
been approved by an organization as the authoritative definition of a
standard.
You may add a passage of up to five words as a Front-Cover Text, and a
passage of up to 25 words as a Back-Cover Text, to the end of the list
of Cover Texts in the Modified Version. Only one passage of
Front-Cover Text and one of Back-Cover Text may be added by (or
through arrangements made by) any one entity. If the Document already
includes a cover text for the same cover, previously added by you or
by arrangement made by the same entity you are acting on behalf of,
you may not add another; but you may replace the old one, on explicit
permission from the previous publisher that added the old one.
The author(s) and publisher(s) of the Document do not by this License
give permission to use their names for publicity for or to assert or
imply endorsement of any Modified Version.
5. COMBINING DOCUMENTS
You may combine the Document with other documents released under this
License, under the terms defined in section 4 above for modified
versions, provided that you include in the combination all of the
Invariant Sections of all of the original documents, unmodified, and
list them all as Invariant Sections of your combined work in its
license notice, and that you preserve all their Warranty Disclaimers.
The combined work need only contain one copy of this License, and
multiple identical Invariant Sections may be replaced with a single
copy. If there are multiple Invariant Sections with the same name but
different contents, make the title of each such section unique by
adding at the end of it, in parentheses, the name of the original
author or publisher of that section if known, or else a unique number.
Make the same adjustment to the section titles in the list of
Invariant Sections in the license notice of the combined work.
In the combination, you must combine any sections Entitled "History"
in the various original documents, forming one section Entitled
"History"; likewise combine any sections Entitled "Acknowledgements",
and any sections Entitled "Dedications". You must delete all sections
Entitled "Endorsements".
6. COLLECTIONS OF DOCUMENTS
You may make a collection consisting of the Document and other documents
released under this License, and replace the individual copies of this
License in the various documents with a single copy that is included in
the collection, provided that you follow the rules of this License for
verbatim copying of each of the documents in all other respects.
You may extract a single document from such a collection, and distribute
it individually under this License, provided you insert a copy of this
License into the extracted document, and follow this License in all
other respects regarding verbatim copying of that document.
7. AGGREGATION WITH INDEPENDENT WORKS
A compilation of the Document or its derivatives with other separate
and independent documents or works, in or on a volume of a storage or
distribution medium, is called an "aggregate" if the copyright
resulting from the compilation is not used to limit the legal rights
of the compilation's users beyond what the individual works permit.
When the Document is included in an aggregate, this License does not
apply to the other works in the aggregate which are not themselves
derivative works of the Document.
If the Cover Text requirement of section 3 is applicable to these
copies of the Document, then if the Document is less than one half of
the entire aggregate, the Document's Cover Texts may be placed on
covers that bracket the Document within the aggregate, or the
electronic equivalent of covers if the Document is in electronic form.
Otherwise they must appear on printed covers that bracket the whole
aggregate.
8. TRANSLATION
Translation is considered a kind of modification, so you may
distribute translations of the Document under the terms of section 4.
Replacing Invariant Sections with translations requires special
permission from their copyright holders, but you may include
translations of some or all Invariant Sections in addition to the
original versions of these Invariant Sections. You may include a
translation of this License, and all the license notices in the
Document, and any Warranty Disclaimers, provided that you also include
the original English version of this License and the original versions
of those notices and disclaimers. In case of a disagreement between
the translation and the original version of this License or a notice
or disclaimer, the original version will prevail.
If a section in the Document is Entitled "Acknowledgements",
"Dedications", or "History", the requirement (section 4) to Preserve
its Title (section 1) will typically require changing the actual
title.
9. TERMINATION
You may not copy, modify, sublicense, or distribute the Document except
as expressly provided for under this License. Any other attempt to
copy, modify, sublicense or distribute the Document is void, and will
automatically terminate your rights under this License. However,
parties who have received copies, or rights, from you under this
License will not have their licenses terminated so long as such
parties remain in full compliance.
10. FUTURE REVISIONS OF THIS LICENSE
The Free Software Foundation may publish new, revised versions
of the GNU Free Documentation License from time to time. Such new
versions will be similar in spirit to the present version, but may
differ in detail to address new problems or concerns. See
http://www.gnu.org/copyleft/.
Each version of the License is given a distinguishing version number.
If the Document specifies that a particular numbered version of this
License "or any later version" applies to it, you have the option of
following the terms and conditions either of that specified version or
of any later version that has been published (not as a draft) by the
Free Software Foundation. If the Document does not specify a version
number of this License, you may choose any version ever published (not
as a draft) by the Free Software Foundation.
ADDENDUM: How to use this License for your documents
To use this License in a document you have written, include a copy of
the License in the document and put the following copyright and
license notices just after the title page:
Copyright (c) YEAR YOUR NAME.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2
or any later version published by the Free Software Foundation;
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
A copy of the license is included in the section entitled "GNU
Free Documentation License".
If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
replace the "with...Texts." line with this:
with the Invariant Sections being LIST THEIR TITLES, with the
Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
If you have Invariant Sections without Cover Texts, or some other
combination of the three, merge those two alternatives to suit the
situation.
If your document contains nontrivial examples of program code, we
recommend releasing these examples in parallel under your choice of
free software license, such as the GNU General Public License,
to permit their use in free software.
]]></literallayout>
</appendix>

54
wcmtools/s2/doc/docbook/bookinfo.xml Executable file
View File

@@ -0,0 +1,54 @@
<bookinfo>
<title>S2 Manual</title>
<authorgroup>
<editor>
<firstname>Jesse</firstname>
<surname>Proulx</surname>
<affiliation>
<address>
<email>jproulx@livejournal.com</email>
</address>
</affiliation>
</editor>
<author>
<firstname>Brad</firstname>
<surname>Fitzpatrick</surname>
<affiliation>
<address>
<email>bradfitz@livejournal.com</email>
</address>
</affiliation>
</author>
<author>
<firstname>Martin</firstname>
<surname>Atkins</surname>
<affiliation>
<address>
<email>mart@livejournal.com</email>
</address>
</affiliation>
</author>
</authorgroup>
<abstract>
<para>
An all-inclusive manual on S2 and using S2 with LiveJournal.
</para>
</abstract>
<legalnotice>
<para>
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version
1.1 or any later version published by the Free Software
Foundation; with no invariant sections, nor Front-Cover/Back-Cover Texts.
A copy of the license is included in <xref linkend='appx.gfdl'/>
</para>
</legalnotice>
<copyright>
<year>1999</year>
<year>2000</year>
<year>2001</year>
<year>2002</year>
<year>2003</year>
<holder><ulink url="http://www.danga.com/">Danga Interactive</ulink></holder>
</copyright>
</bookinfo>

6
wcmtools/s2/doc/docbook/caveats.xml Executable file
View File

@@ -0,0 +1,6 @@
<title>Caveats</title>
<section id='&s2.idroot;caveats.printhtml'>
<title>Untrusted layers printing incomplete HTML.</title>
<para>All output from the print command in untrusted layers gets piped through the HTML cleaner which militantly cleans HTML, removing anything that's harmful or potentially harmful. Because styles can contain both user layers and trusted system layers, both of which can be printing, a print from a trusted layer flushes the HTML cleaner's buffer, forcing it to finish earlier than it might otherwise wish to. For instance, if an untrusted layer prints out an incomplete tag, normally the HTML cleaner waits until it sees the rest before sending it along to the client. But if a trusted layer forces a flush, the HTML cleaner may be confused and forced to over-escape a lot of HTML to be safe.</para>
<para>To avoid this problem print only complete tags at once, or avoid calling other code which may switch into trusted code.</para>
</section>

172
wcmtools/s2/doc/docbook/csp.xml Executable file
View File

@@ -0,0 +1,172 @@
<title>S2 Client Protocol</title>
<para>
This protocol, initially implemented for
<ulink url="http://www.livejournal.com/">LiveJournal</ulink> but applicable
elsewhere, provides a machine-friendly interface to an S2 system on a
remote server.
</para>
<para>
The protocol is just HTTP, so you can implement it using any suitable HTTP
library, including the Perl LWP library.
</para>
<section id="&s2.idroot;csp.general">
<title>General Rules</title>
<para>
A new <parameter>Content-type</parameter> value is introduced for S2 layers, named
<literal>application/x-danga-s2-layer</literal>. This is used both in server
responses and client layer uploads.
</para>
<section id="&s2.idroot;csp.general.request">
<title>Requests</title>
<para>
When making a request to the S2 interface, you can authenticate with the
remote server using either HTTP Digest authentication<footnote id="&s2.idroot;csp.general.ftn.digest_auth">
<simpara>
Refer to <ulink url="http://www.faqs.org/rfcs/rfc2617.html">RFC 2617</ulink>
for more information.
</simpara>
</footnote>
or some site-specific authentication method. On LiveJournal, session
cookies are supported.
</para><para>
The request URL will vary between applications. On LiveJournal it can be
found at <systemitem class="systemname">/interface/s2</systemitem>.
</para><para>
The same URL is used for both retrieval and updating; the method used
defines the action the server will take. On LiveJournal, that URL wil be
<systemitem class="systemname">/interface/s2/<replaceable>layerid</replaceable></systemitem>.
How you find the correct layerid is outside the scope of this specification.
</para>
</section>
<section id="&s2.idroot;csp.general.response">
<title>Responses</title>
<para>
When parsing response bodies, consider only ASCII character 10 (newline, \n)
to indicate a newline. Disregard any occurances of ASCII 13 (carriage return, \r).
</para><para>
Error responses will have an HTTP error code and have a plain text
response body. This will contain a short error message, then a newline,
then a longer error message also followed by a newline, and optionally
other data which you may wish to display.
</para><para>
If the response is not in the expected format (ie, content-type does not
indicate a plain text response) clients should simply explain that the
server has returned an invalid response and that this might be temporary
or due to an incorrect URL. Even in the case of an unparsable body, the
HTTP response code can be used to infer the nature of the error.
</para><para>
You should be prepared to accept any HTTP response code and treat it as
the HTTP spec describes. This includes the redirection codes. You are
advised to use a full HTTP library, which is available for most
languages, to make your requests rather than hacking up flakey HTTP code
which assumes everything will always work in a particular way.
</para><para>
An exception to this rule is that the <returnvalue>403 Forbidden</returnvalue>
response is defined in HTTP to indicate that "authentication will not help",
but this protocol also allows for it to describe the condition where authentication
credentials are given but the given account has no access to whatever was
being retrieved. This slight quirk is made under the assumption that many
clients for this protocol will be non-interactive and launched as tools
from text editors, and prompting for alternative credentials would be
impossible.
</para>
</section>
</section>
<section id="&s2.idroot;csp.download">
<title>Retrieve Layer Source</title>
<para>
In order to get the S2 source of a layer for local editing, a simple GET
request is sufficient:
</para>
<programlisting>GET /interface/s2/1 HTTP/1.0
Host: www.livejournal.com
Accept: application/x-danga-s2-layer</programlisting>
<para>
In addition to the basic headers shown above, some form of authentication
can be used. See the HTTP specification for documentation on Basic
authentication. Anonymous requests are allowed, but the server may respond
with <returnvalue>401 Unauthorized</returnvalue>, describing the standard HTTP
authentication methods supported. Some servers, as described above, may
implement "special" authentication methods, such as LiveJournal supporting
website session cookies. These are not described (in a machine-readable way,
at least) in the Unauthorized response.
</para>
<para>
Client authors are <emphasis>strongly advised</emphasis> to send the
<parameter>Accept</parameter> header, as in the future other formats
may be supported and the server will be able to see which
format you are expecting and either honour your request or return the
response <returnvalue>Unnacceptable</returnvalue> if S2 layer source
as we know it now is unavailable.
</para>
<para>
If the response is an error, the response body will contain a short error
and then a longer error separated by a newline character, plus optionally
further error lines which you may wish to display if they are present. The
HTTP response code will give you some idea of the nature of the error.
</para>
<para>
If the response is successful (response code is 200 OK), and the
<parameter>content-type</parameter> is <literal>application/x-danga-s2-layer</literal>,
you will find S2 source in the response body. As with error responses,
you should consider only ASCII 10 (\n) to mean newline. Disregard ASCII 13
(\r). You may transform the returned \n characters to the local newline
representation for output if you wish.
</para>
</section>
<section id="&s2.idroot;csp.upload">
<title>Upload a Layer</title>
<para>
This mechanism can only be used to update an existing layer. This version
of the protocol does not allow for new layers to be created via the
interface. The S2 application will provide some mechanism, probably
human-oriented, to do this.
</para>
<para>
Uploading is done via an HTTP PUT request. The URL is the same used to
retrieve the given layer.
</para>
<programlisting>PUT /interface/s2/1 HTTP/1.0
Host: www.livejournal.com
Content-Length: 65
Content-Type: application/x-danga-s2-layer
layerinfo "type" = "layout";
layerinfo "name" = "Upload Example";
...
</programlisting>
<para>
If the given layer is an acceptable replacement for the layer indicated,
the server will respond with either <returnvalue>201 Created</returnvalue>,
which means that the layer is accepted and has been updated on the system,
or <returnvalue>202 Accepted</returnvalue>, indicating that the layer was
acceptable but the system will not instantly replace the existing layer
with it for reasons unspecified.
</para>
<para>
The server can also respond with any HTTP error code. The code
<returnvalue>500</returnvalue> is used to indicate that the server is unable
to accept the layer. If this is due to a layer compile error, the error will
be given in the optional part of the error response after the short and long
error descriptions.
</para>
<note>
<title>Optional Client Features</title>
<simpara>
A client with access to a local S2 compiler may wish to perform a
syntax check on the layer to be uploaded to avoid a round-trip to
the server for a syntax problem which could be resolved locally.
However, an option to override this should be provided to allow
for future changes to S2 syntax which may cause parse errors in
older versions of the compiler.
</simpara><simpara>
It is not advisable for the local client to attempt the checker
phase of compilation, as this is slow and local copies of parent
layers will frequently become out of date with that on the server.
</simpara>
</note>
</section>

26
wcmtools/s2/doc/docbook/design.xml Executable file
View File

@@ -0,0 +1,26 @@
<title>Design Goals</title>
<itemizedlist>
<listitem><para>Easy and flexible for beginners</para>
<para>End users who aren't programmers should be able to have an extreme amount of control over their journals without ever seeing or knowing HTML, CSS, hex color codes, or other web geekery. The styles and themes should have graphical previews and graphical wizards to customize every color, option, and text.</para>
</listitem>
<listitem><para>Powerful, familiar, and powerful for geeks</para>
<para>The core of S2 is actually a programming language, with syntax and semantics resembling Perl/C++/Java/etc. People who do know how to program will be able to do anything they want, including make styles which all their non-geek friends will able to use, since the styles are capable of reflecting all their options, which the graphical wizard lets them tweak.</para>
<para>Developers shouldn't have to write a lot of repeated or unnecessary code. Authors of layouts need not override all functionality, instead being able to fall back on the core-provided functionality.</para>
</listitem>
<listitem><para>Security</para>
<para>Rather than letting users program directly in C or Perl, S2 ensures that the resultant compiled code is both safe and fast.</para>
<para>S2 code can't get access to anything on the host machine or do anything malicious.</para>
<para>S2 code can't waste host machine resources. (CPU or memory)</para>
<para>Untrusted S2 code can't print JavaScript to prevent people from making styles which read their visitor's session cookies.</para>
</listitem>
<listitem><para>Speed</para>
<para>Internally, S2 code is compiled into a lower level language and run directly when the page is loaded. Unlike S1, no parsing is necessary at run time. Also, S2 outputs directly to the client instead of being entirely buffered in memory first like S1, since S2 doesn't need to do tons of templating replacements at the end.</para>
<para>Trusted code by default prints direct to the client without going through the HTML cleaner. Untrusted, user-created layers send all their output through an HTML cleaner which removes JavaScript and other potentially harmful markup.</para>
<para>Popular S2 code &amp; data is cached by the webserver.</para>
</listitem>
<listitem><para>Internationalization</para>
<para>S1 was English-centric. If you wanted to say "1 comment" vs "2 comments", you used the magical %%s%% which was an es when plural and nothing otherwise. But then of course we had to make a magical %%ies%% for "1 reply" vs "2 replies". This ignores languages where the plural form is entirely different, or there are multiple plural forms.</para>
<para>S2 uses UTF-8 everywhere, handles plural forms correctly, and makes customizing text/date formats/etc all trivial.</para>
<para>S2 makes it possible for languages to override not only the text which will appear in the final output, but all the property names and descriptions as well, so understanding English is never a requirement to customize the look of one's content.</para>
</listitem>
</itemizedlist>

25
wcmtools/s2/doc/docbook/entities.xml Executable file
View File

@@ -0,0 +1,25 @@
<!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 s2.faq.extra "">
<!ENTITY appx.gfdl SYSTEM "appx.gfdl.xml">

27
wcmtools/s2/doc/docbook/faq.xml Executable file
View File

@@ -0,0 +1,27 @@
<title>FAQ</title>
<qandaset defaultlabel='qanda'>
<qandaentry id='&s2.idroot;faq.xslt'>
<question><simpara>Why didn't you just use XML and let style authors use XSLT?</simpara></question>
<answer><simpara><ulink url="http://www.livejournal.com/users/evan/601685.html">Because XSLT is ugly and difficult.</ulink></simpara></answer>
</qandaentry>
<qandaentry id='&s2.idroot;faq.newlang'>
<question><simpara>Why invent a whole new programming language and not just use, say, Perl and Safe.pm?</simpara></question>
<answer><para>Believe me, a lot of options were considered. There are a number of reasons we "reinvented the wheel":</para>
<itemizedlist>
<listitem><simpara>The other wheels weren't round.</simpara></listitem>
<listitem><simpara>Safe.pm isn't too safe.</simpara></listitem>
<listitem><para>By making our own domain language, we make it easy to do the things which are common/specific to this problem. A short list:
<itemizedlist>
<listitem><simpara>The common operation is print. So we made an expression statement starting with a string literal be a print statement on that expression.</simpara></listitem>
<listitem><simpara>Large blocks of text are printed often, so we wanted the Python-style triple-quoted string literals.</simpara></listitem>
<listitem><simpara>We wanted <link linkend='&s2.idroot;layers'>layers</link> of functionality/overridability.</simpara></listitem>
<listitem><simpara>We wanted a graphical wizard to be able to look inside the layers and see what options are available.</simpara></listitem>
</itemizedlist>
</para></listitem>
<listitem><simpara>It wasn't that hard.</simpara></listitem>
<listitem><simpara>The language is very similar to other languages which geeks are already familiar with. The learning curve isn't too steep.</simpara></listitem>
</itemizedlist>
</answer>
</qandaentry>
&s2.faq.extra;
</qandaset>

10
wcmtools/s2/doc/docbook/history.xml Executable file
View File

@@ -0,0 +1,10 @@
<title>History and Motivation</title>
<para>S2 (Style System 2) is the follow-up to LiveJournal's original templating engine, now referred to as "S1". S1 allowed people who knew HTML to somewhat easily re-style their journal but had a number of shortcomings:</para>
<itemizedlist>
<listitem><para>The four views (recent ("lastn"), friends, calendar, and day) all had to be created independently and couldn't share any code. So if you wanted to make a new style you had to do it four times. The tediousness of this made us reluctant to add any more views to the system (such as a month view or single item/comments view).
<itemizedlist>
<listitem><simpara>Styles weren't easily customizable, and thus not well-suited for the majority of users. While there existed the idea of "color themes", they were ill-designed in that it was assumed any color theme should be able to plug into any style. The available colors to set (by the themes) and use (by the styles) were named things like "background", "foreground", "weak accent", "text on weak accent", "strong accent", etc.. Unfortunately, no color theme worked well with every layout and no layout worked well with all color theme. In S2, color themes are specific to the layout.</simpara></listitem>
<listitem><simpara>Colors were the only things that were easily customizable. Other options required editing HTML or doing CSS, both things which the average user neither knows nor should know.</simpara></listitem></itemizedlist></para></listitem>
<listitem><simpara>S1 didn't give style authors much flexibility, since it didn't offer any way to do conditional output. Instead, the system itself has to anticipate author needs and conditionally populate and provide certain template blocks, depending on whether there's, say, an entry subject or not. S2, on the other hand, is a full programming langauge, so authors can do whatever they want.</simpara></listitem></itemizedlist>
<para>S2 addresses all these problems. But fear not: S1 will stick around for those who prefer it and/or those who don't want to make the jump to S2 just yet. But we believe we'll win everybody over eventually once they give it a shot.</para>

36
wcmtools/s2/doc/docbook/how.xml Executable file
View File

@@ -0,0 +1,36 @@
<title>Behind the Scenes</title>
<section id='&s2.idroot;howworks'>
<title>How it all works, in a nutshell</title>
<para>
The web app get a request and decides what user it's for, and what type of resource it's for.
</para>
<para>The web application loads the user's style for that resource and then loads each
layer for that style, unless it's already loaded. (layers are selectively cached) </para>
<para>
The S2 system builds a <emphasis role="bold">context</emphasis> which contains the property values
set by the top-most layer for each property, as well as a function vtable
computed the same way. </para>
<para>
Next the web application invokes the global <function>prop_init()</function> function which the layout layer might've
implemented. The job of this function is to initialize the <emphasis role="bold">constructional properties</emphasis>.
Constructional properties are properties which the web app looks at to influence
its subsequent data structure population. For example, FotoBilder examines
the value of <varname>$*gallery_max_page_size</varname> to determine how many thumbnails
to load and return for a gallery. However, a layout wouldn't always want
to directly expose this property to the users. What if the layout was a
grid and the user wanted a page size that was a prime number? How do you
make an even grid out of 37 pictures? This sort of layout should ask the
user for the number of rows and columns they want, then compute <varname>$*gallery_max_page_size</varname>
in <function>prop_init()</function> by multiplying <varname>$*rows</varname> and <varname>$*cols</varname>.
</para>
<para> The web app looks at the current context and determines both the version
number of the core layer and the values of all the constructional properties,
then builds an appropriate data-structure for the resource requested. This
instantiated object is likely pretty deep, containing dozens of instantiated
objects all hanging off it. </para>
<para>
The web app invokes the entry point method (probably called <function>-&gt;print()</function>)
on the object it just instantiated. From here, S2 code runs, printing what
it wants, and invoking methods on other objects in its huge data structure
which may also print. </para>
</section>

27
wcmtools/s2/doc/docbook/index.xml Executable file
View File

@@ -0,0 +1,27 @@
<?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;preface'>
&s2.preface;
</chapter>
<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>
<appendix id='&s2.idroot;faq'>
&s2.faq;
</appendix>
&appx.gfdl;
</book>

654
wcmtools/s2/doc/docbook/langref.xml Executable file
View File

@@ -0,0 +1,654 @@
<title>Language Reference</title>
<section id='&s2.idroot;langref.overview'>
<title>S2 Language Overview</title>
<para>The S2 language is an object-oriented and statically-typed language with syntax mostly
borrowed from Perl, but with some borrowings from other languages including Java and Python.</para>
<para>This language is domain-specific, which means that it has a reduced feature set compared
to general-purpose programming languages you may be familiar with. In particular, the
flow control constructs available are restricted to conditional branching (<quote>if</quote> statements)
and iteration over finite lists (<quote>foreach</quote> loops).</para>
<para>The language has several features which are designed to make life easier:
<itemizedlist>
<listitem><simpara>Variables can be referenced from within string literals, in which
case their values will be interpolated into the resulting string. This
behavior is similar to perl.</simpara></listitem>
<listitem><simpara>String literals can be given enclosed in three sets of quotes
(<literal>"""</literal>), which allows quote characters to be included
within the string unescaped. This is useful for producing HTML which
features lots of quote symbols.</simpara></listitem>
<listitem><simpara>String expressions can be used as statements, causing their
value to be implicitly output to the client.</simpara></listitem>
<listitem><simpara><emphasis>Properties</emphasis> can be defined which
are special global variables exposed from a layer to be set
from other layers or from a friendly customization interface.</simpara></listitem>
</itemizedlist>
</para>
<para>This section serves as a reference guide for the S2 language. Anyone who is familiar
with procedural programming should be right at home. If you have not done programming
before, you may like to get an idea of the concepts behind programming before you
begin.</para>
</section>
<section id='&s2.idroot;langref.literals'>
<title>Literals</title>
<para>S2 supports integer, string, boolean, array and hash literals:</para>
<variablelist>
<varlistentry>
<term><parameter>123</parameter></term>
<listitem><simpara>Integer literal representing the number <quote>one hundred and twenty three</quote>.</simpara></listitem>
</varlistentry>
<varlistentry>
<term><parameter>"Blah blah blah"</parameter></term>
<listitem><simpara>Simple string literal. Variables are interpolated and escape sequences are processed.</simpara></listitem>
</varlistentry>
<varlistentry>
<term><parameter>"""string with "quotes" in it"""</parameter></term>
<listitem><simpara>Triple-quote string literal. Quotes can occur within with no escaping for one or two consecutive characters. Variables are interpolated and escape sequences are processed.</simpara></listitem>
</varlistentry>
<varlistentry>
<term><parameter>true</parameter></term><term><parameter>false</parameter></term>
<listitem><simpara>The two boolean literals.</simpara></listitem>
</varlistentry>
<varlistentry>
<term><parameter>[ item, item, item, item ]</parameter></term>
<listitem><simpara>Array literal. All items must be of the same type, and this literal will return an array of that type. Trailing commas are fine, if you want to include them.</simpara></listitem>
</varlistentry>
<varlistentry>
<term><parameter>{ key => value, key => value, key => value }</parameter></term>
<listitem><simpara>Array literal. All <quote>key</quote> items must be strings, and all <quote>value</quote> items must be of the same type. This literal will return a hash of that type.</simpara></listitem>
</varlistentry>
</variablelist>
<para>The following escape sequences are supported in strings:</para>
<variablelist>
<varlistentry>
<term><literal>\n</literal></term>
<listitem><simpara>Newline</simpara></listitem>
</varlistentry>
<varlistentry>
<term><literal>\"</literal></term>
<listitem><simpara>Literal quote</simpara></listitem>
</varlistentry>
<varlistentry>
<term><literal>\\</literal></term>
<listitem><simpara>Literal backslash</simpara></listitem>
</varlistentry>
<varlistentry>
<term><literal>\$</literal></term>
<listitem><simpara>Literal dollarsign</simpara></listitem>
</varlistentry>
</variablelist>
</section>
<section id='&s2.idroot;langref.variables'>
<title>Variables</title>
<para>S2 supports several primitive types, as well as regular and associative arrays and objects based on classes.</para>
<section id='&s2.idroot;langref.variables.types'>
<title>Variable Types</title>
<para>S2 has the following primitive types:</para>
<variablelist>
<varlistentry>
<term><literal>int</literal></term>
<listitem><simpara>An integer</simpara></listitem>
</varlistentry>
<varlistentry>
<term><literal>bool</literal></term>
<listitem><simpara>A boolean (true/false) value</simpara></listitem>
</varlistentry>
<varlistentry>
<term><literal>string</literal></term>
<listitem><simpara>A string</simpara></listitem>
</varlistentry>
</variablelist>
</section>
<section id='&s2.idroot;langref.variables.declaration'>
<title>Declaration</title>
<variablelist>
<varlistentry>
<term><literal>var int somenumber;</literal></term>
<listitem><simpara>Declare a simple variable named somenumber as an integer.</simpara></listitem>
</varlistentry>
<varlistentry>
<term><literal>var string[] names</literal></term>
<listitem><simpara>Declare a regular array of strings called names.</simpara></listitem>
</varlistentry>
<varlistentry>
<term><literal>var bool{} has_stuff</literal></term>
<listitem><simpara>Declare an associative array of boolean values called has_stuff.</simpara></listitem>
</varlistentry>
<varlistentry>
<term><literal>var SomeClass[] stuffs</literal></term>
<listitem><simpara>Declare a regular array of the class SomeClass and name it stuffs.</simpara></listitem>
</varlistentry>
<varlistentry>
<term><literal>var SomeClass{} stuffs</literal></term>
<listitem><simpara>Declare an associative array of the class SomeClass and name it stuffs.</simpara></listitem>
</varlistentry>
</variablelist>
</section>
<section id='&s2.idroot;langref.variables.access'>
<title>Access</title>
<variablelist>
<varlistentry>
<term><literal>$variable</literal></term>
<listitem><simpara>Returns the value stored in the variable, or reference to the regular or associative array or instance of a class with this name.</simpara></listitem>
</varlistentry>
<varlistentry>
<term><literal>$this</literal></term>
<listitem><simpara>An instance of the class the currently-executing function was envoked from.</simpara></listitem>
</varlistentry>
<varlistentry>
<term><literal>$.member</literal></term><term><literal>$this.member</literal></term>
<listitem><simpara>Equivalent ways to return the value stored in this member of the class which owns the function being executed.</simpara></listitem>
</varlistentry>
<varlistentry>
<term><literal>$var.member</literal></term>
<listitem><simpara>Returns the value stored in this member of the instance of a class known as <classname>var</classname>.</simpara></listitem>
</varlistentry>
<varlistentry>
<term><literal>$*propertyname</literal></term>
<listitem><simpara>Returns the value of the property specified.</simpara></listitem>
</varlistentry>
<varlistentry>
<term><literal>$variable[2]</literal></term>
<listitem><simpara>Returns the value stored in element 2 (3rd element) of the regular array.</simpara></listitem>
</varlistentry>
<varlistentry>
<term><literal>$variable{"fred"}</literal></term>
<listitem><simpara>A value stored in the associative array.</simpara></listitem>
</varlistentry>
</variablelist>
</section>
</section>
<section id='&s2.idroot;langref.operators'>
<title>Operators</title>
<para>S2 operators have the following associativity and precedence, listed from highest precedence to lowest.</para>
<informaltable frame='none'>
<tgroup cols='2'>
<colspec colwidth="2*" />
<tbody>
<row><entry>left</entry><entry>Terms (literals, expressions in parentheses, variables, function/method calls, named unary operators)</entry></row>
<row><entry>nonassoc</entry><entry>++ --</entry></row>
<row><entry>right</entry><entry>not -</entry></row>
<row><entry>left</entry><entry>* / %</entry></row>
<row><entry>left</entry><entry>+ -</entry></row>
<row><entry>nonassoc</entry><entry><![CDATA[< > <= >=]]></entry></row>
<row><entry>nonassoc</entry><entry>== !=</entry></row>
<row><entry>left</entry><entry>and</entry></row>
<row><entry>left</entry><entry>or</entry></row>
<row><entry>nonassoc</entry><entry>..</entry></row>
<row><entry>nonassoc</entry><entry>? :</entry></row>
<row><entry>right</entry><entry>=</entry></row>
</tbody>
</tgroup>
</informaltable>
<section id="&s2.idroot;langref.operators.arithmetic">
<title>Arithmetic Operators</title>
<para>The S2 language has the usual set of arithmetic operators you'd expect to find in a programming
language. These are the same as the arithmetic operators in perl.</para>
<para>As you might expect, these operators can only be applied to integers, and will return integers.</para>
<informaltable frame='none'>
<tgroup cols='3'>
<tbody>
<row><entry><literal>+</literal></entry><entry>binary</entry><entry>Addition</entry></row>
<row><entry><literal>-</literal></entry><entry>binary</entry><entry>Subtraction</entry></row>
<row><entry><literal>*</literal></entry><entry>binary</entry><entry>Multiplication</entry></row>
<row><entry><literal>/</literal></entry><entry>binary</entry><entry>Division</entry></row>
<row><entry><literal>%</literal></entry><entry>binary</entry><entry>Modulus (remainder)</entry></row>
<row><entry><literal>++</literal></entry><entry>unary</entry><entry>Increment in-place</entry></row>
<row><entry><literal>--</literal></entry><entry>unary</entry><entry>Decrement in-place</entry></row>
<row><entry><literal>-</literal></entry><entry>unary</entry><entry>Negation</entry></row>
</tbody>
</tgroup>
</informaltable>
</section>
<section id="&s2.idroot;langref.operators.comparison">
<title>Comparison Operators</title>
<para>These operators allow you to compare one value to another. Both operands must be of the
same type, and all but simple equality/inequality can only be applied to integers. Only primitive
types may be compared with these operators. All comparison operators return a boolean value.</para>
<informaltable frame='none'>
<tgroup cols='3'>
<tbody>
<row><entry><literal>==</literal></entry><entry>binary</entry><entry>Equals</entry></row>
<row><entry><literal>!=</literal></entry><entry>binary</entry><entry>Does not equal</entry></row>
<row><entry><literal>&lt;</literal></entry><entry>binary</entry><entry>Less than</entry></row>
<row><entry><literal>&gt;</literal></entry><entry>binary</entry><entry>Greater than</entry></row>
<row><entry><literal>&lt;=</literal></entry><entry>binary</entry><entry>Less than or equal to</entry></row>
<row><entry><literal>&gt;=</literal></entry><entry>binary</entry><entry>Greater than or equal to</entry></row>
</tbody>
</tgroup>
</informaltable>
</section>
<section id="&s2.idroot;langref.operators.logical">
<title>Logical Operators</title>
<para>These operators perform logical operations on boolean values. All operands must be boolean,
and a boolean value results.</para>
<informaltable frame='none'>
<tgroup cols='3'>
<tbody>
<row><entry><literal>and</literal></entry><entry>binary</entry><entry>Logical AND</entry></row>
<row><entry><literal>or</literal></entry><entry>binary</entry><entry>Logical OR</entry></row>
<row><entry><literal>not</literal></entry><entry>unary</entry><entry>Logical complement</entry></row>
</tbody>
</tgroup>
</informaltable>
<para>In summary, AND returns true if and only if both of its operands are true. OR returns true if
one or both of its operands are true. NOT returns true if its operand is false, and false otherwise.</para>
<para>The two binary logical operators are usually used in an <literal>if</literal> statement to
include two or more comparisons.</para>
</section>
<section id="&s2.idroot;langref.operators.other">
<title>Other Operators</title>
<para>These operators don't really fit into a category of their own, and have perhaps non-obvious functions.</para>
<section>
<title>The assignment operator: <literal>=</literal></title>
<para>The assignment operator (which should not be confused with the equality test operator, <literal>==</literal>),
is used to assign a value to a named variable. This means that unlike most other operators, its
left operand <emphasis>must</emphasis> be a variable name. No other kind of expression will do.</para>
<para>The assignment operator can take operands of any type, but the right-hand operand must
be of the same type as the variable given on the left, or <emphasis>coercable</emphasis> into
that type.</para>
<para>The assignment operator also returns whatever value it has just assigned to the variable,
meaning that you can chain several assignments together as follows:
<programlisting>$foo = $bar = $baz = 2;</programlisting>
In this case, <varname>$foo</varname>, <varname>$bar</varname> and <varname>$baz</varname>
will all be assigned the value 2.</para>
<para>As a special case, assignment can also be used when declaring local variables:
<programlisting>var string $name = "John";</programlisting>
However, this is only true for local variables. Class variables cannot be initialized
in this way.</para>
<para>The symbol <literal>=</literal> is used for several other assignment-like things
in the S2 language, including setting property values and layerinfo. These aren't really
assignment, but act similarly and in the case of property setting follow many of the
rules described above.</para>
</section>
<section>
<title>String Concatenation with <literal>+</literal></title>
<para>The <literal>+</literal> symbol actually has two purposes in the S2 language. When
one of its operands is a string, it becomes the <emphasis>string concatenation operator</emphasis>.
In this form, it will firstly attempt to coerce any non-string operand into a string,
then stick the two strings together to form a resulting string which is returned.</para>
<para>The simplest form of string concatenation involves two strings. In this case,
both strings are just concatenated and that is it. However, as long as one operand
remains a string, the other operand can be an integer, a boolean or an object with
certain conditions. Objects may only be concatenated to strings if their class has
an <function>as_string()</function> method which returns a string. The return
value of this method will be used as the string value for concatenation.</para>
<para>String literals with interpolated variables are really just concatenation
with a more convenient syntax, which is why you are able to interpolate integers
and certain objects directly into string literals.</para>
</section>
<section>
<title>The ternary conditional operator <literal>? :</literal></title>
<para>This is the only operator in the S2 language with three operands. Its
function can be thought of as being like an <literal>if</literal> statement
in the form of an operator.</para>
<para>This operator is best explained with an example:
<programlisting>$label = ($c == 1 ? "1 comment" : "$c comments");</programlisting>
In this example, the conditional operator and its operands are enclosed
in parenthesis for clarity. These are optional, but can make things more readable.
The first operand, preceding the question-mark symbol, is a boolean expression. In
this case it is an equality test. If this expression evaluates to true, the second
operand, which is after the question-mark and before the colon, is returned. If
the expression is false, the third operand is returned.</para>
<para>The first operand <emphasis>must</emphasis> be a boolean expression. The second
and third operands can be of any type but their types must match. The return type
of this operator is the same as that of the second and third operand. In the
above example, then, the return type would be string.</para>
<para>In all cases an <literal>if</literal> construct can be used in place
of this operator, but the conditional operator is shorter and more readable
in some cases.</para>
</section>
<section>
<title>The range operator <literal>..</literal></title>
<para>This rather quirky operator is borrowed from Perl. It takes two
integer operands and returns an array of integers containing all integers
between the first and second operand, inclusive. For example:
<programlisting>var int[] list = 1 .. 10;</programlisting>
The array <varname>$list</varname> will now contain ten elements,
each numbered in order from 1 to 10. This has the same effect as:
<programlisting>var int[] list = [1,2,3,4,5,6,7,8,9,10];</programlisting>
</para>
<para>This operator is really only useful for creating a loop which
will iterate a certain number of times:
<programlisting>foreach var int i (1 .. 10) {
println "Iteration number $i";
}</programlisting>
This example will print ten lines, each containing a number from 1 to 10 in order.</para>
<note>
<para>Some readers will probably balk at the use of an array of integers to
create a loop such as this, as it would use more memory than a conventional
<literal>for</literal> loop from a general programming language.</para>
<para>However, you don't have to worry. The above idiom is optimised
to an efficient form at compile time, so there is no memory wasted.</para>
</note>
</section>
</section>
<section id="&s2.idroot;langref.operators.unary">
<title>Named Unary Operators</title>
<simpara>The following are the built-in named operators. You do not have to wrap the following term in parentheses.</simpara>
<variablelist>
<varlistentry>
<term><function>isnull</function> <varname>$object</varname></term>
<listitem><simpara>returns a boolean: true if <varname>$object</varname> is null (has no value)</simpara></listitem>
</varlistentry>
<varlistentry>
<term><function>defined</function> <varname>$object</varname></term>
<listitem><simpara>opposite of <function>isnull</function>. might be prettier than negating <function>isnull</function></simpara></listitem>
</varlistentry>
<varlistentry>
<term><function>new</function> <varname>ClassName</varname></term>
<listitem><simpara>returns an instance of <varname>ClassName</varname> with all members empty or zero</simpara></listitem>
</varlistentry>
<varlistentry>
<term><function>newnull</function> <varname>ClassName</varname></term>
<listitem><simpara>returns an undefined value of type <varname>ClassName</varname></simpara></listitem>
</varlistentry>
<varlistentry>
<term><function>reverse</function> <varname>$string</varname></term>
<listitem><simpara>returns copy of <varname>$string</varname> with characters reversed</simpara></listitem>
</varlistentry>
<varlistentry>
<term><function>reverse</function> <varname>$array</varname></term>
<listitem><simpara>returns shallow copy of <varname>$array</varname> with elements reversed.</simpara></listitem>
</varlistentry>
<varlistentry>
<term><function>size</function> <varname>$string</varname></term>
<listitem><para>returns number of <emphasis>bytes</emphasis> in <varname>$string</varname>.
This behavior is deprecated. Please see note below.</para></listitem>
</varlistentry>
<varlistentry>
<term><function>size</function> <varname>$array</varname></term>
<listitem><simpara>returns number of elements in <varname>$array</varname></simpara></listitem>
</varlistentry>
</variablelist>
<note><simpara>The use of the <function>size</function> operator on strings is deprecated and
will be removed or updated without notice. Instead, you should use the string class's length
method to get the number of <emphasis>characters</emphasis>. Remember that some characters
are represented by more than one byte.</simpara></note>
</section>
</section>
<section id='&s2.idroot;langref.statements'>
<title>Statements</title>
<para>A statement is an expression terminated by a semicolon. Statements can contain <literal>code blocks</literal> delimited by curly braces which can then contain one or more statements themselves. Flow control constructs can also be statements.</para>
<para>A statement consisting wholly of a string literal, or a string literal with other strings concatenated to it will be output to the client. A statement consisting wholly of a variable will behave similarly.</para>
<para>The <function>print</function> instruction will cause the string or numeric expression supplied as its parameter to be output to the client. The <function>print safe</function> alternative does similarly, but forces the output to be checked for <quote>safety</quote>. In the case of LiveJournal and FotoBilder, this means running a <acronym>HTML</acronym> cleaner. All untrusted (non-system) layers always run through the checker, reglardless of which print instuction is used.</para>
<section id='&s2.idroot;langref.statements.flow'>
<title>Flow Control</title>
<para>A limited subset of the flow control constructs normally present in high-level programming languages is available in S2. Each includes at least one code block enclosed in curly braces.</para>
<variablelist>
<varlistentry>
<term><literal>if ( expr ) block</literal></term>
<listitem><simpara>Simple conditional. If <literal>expr</literal> evaluates to true, <literal>block</literal> will be executed, otherwise it will be skipped.</simpara></listitem>
</varlistentry>
<varlistentry>
<term><literal>if ( expr ) block1 else block2</literal></term>
<listitem><simpara>If <literal>expr</literal> evaluates to true, <literal>block1</literal> will be executed, otherwise <literal>block2</literal> will be executed.</simpara></listitem>
</varlistentry>
<varlistentry>
<term><literal>if ( expr1 ) block1 elseif ( expr2 ) block2 else block3</literal></term>
<listitem><simpara>If <literal>expr</literal> evaluates to true, <literal>block1</literal> will be executed. Otherwise, <literal>expr2</literal> will be tested and if it evaluates to true, <literal>block2</literal> will be executed. If both <literal>expr1</literal> and <literal>expr2</literal> evaluate to false, <literal>block3</literal> is executed.</simpara></listitem>
</varlistentry>
<varlistentry>
<term><literal>foreach var ( expr ) block</literal></term>
<listitem><simpara><literal>block</literal> will be executed once for each element in the regular or associative array given in <literal>expr</literal>. On each iteration, an element of the array (or key of an associative array element) will be placed into the variable declared in <varname>var</varname>. <function>foreach</function> can also be used on strings, in which case the iteration variable must be a string and this variable will contain a character from the string with each iteration.</simpara></listitem>
</varlistentry>
</variablelist>
</section>
</section>
<section id='&s2.idroot;langref.classes'>
<title>Classes</title>
<para>Base classes are defined using the following syntax:</para>
<programlisting>class Image {
var string url;
var int w;
var int h;
var string alt;
var string extrahtml;
var string title;
var string longdesc;
function output;
}</programlisting>
<para>A subclass of any class can be created as follows:</para>
<programlisting>class Button extends Image {
var string linkurl;
var int bordersize;
}</programlisting>
<para>All members of <classname>Image</classname> are now valid in <classname>Button</classname>, with the addition of our two new members <varname>linkurl</varname> and <varname>bordersize</varname>. The function <methodname>Button::output</methodname> will override <methodname>Image::output</methodname> if it exists, otherwise <methodname>Image::output</methodname> will be used as a fallback.</para>
<para>See the <link linkend="&s2.idroot;langref.variables">variable</link> and <link linkend="&s2.idroot;langref.functions">function</link> reference for the syntax for accessing members of classes.</para>
</section>
<section id='&s2.idroot;langref.functions'>
<title>Functions</title>
<para>Functions in S2 can be simple functions, methods of a class, or call functions written in the backend language from the <literal>builtin</literal> layer.</para>
<para>Functions can return data in any simple internal datatype, or <returnvalue>void</returnvalue> if no return data is required.</para>
<section id='&s2.idroot;langref.functions.declaration'>
<title>Declaration</title>
<para>Declaring a function within a class is done as follows:
<programlisting>class SomeClass {
function do_stuff(int para1, string para2) : string;
}</programlisting></para>
<para>This declares a function called <methodname>do_stuff</methodname> in the
<classname>SomeClass</classname> class with two parameters and which returns
a string. The colon and type keyword may be omitted where a function will
return <returnvalue>void</returnvalue> (no value).</para>
<para>Functions outside classes are declared in the same way:
<programlisting>function do_global_stuff(int para1, string para2);</programlisting></para>
<para>Functions outside classes do not need to be declared, but if they are not declared they must be defined before they are called.</para>
<para>Built-in functions can be declared in the core layer using the <literal>builtin</literal> keyword in the function prototype:
<programlisting>function builtin ehtml(string s) : string;
class string {
function builtin ends_with (string sub) : bool;
}</programlisting></para>
<para>Functions can have some or no parameters, in the latter case the parentheses may be omitted in declaration. If several functions of the same name exist with different parameters, they can be defined as follows:</para>
<programlisting>function dostuff(int para1);
function dostuff;</programlisting>
<para>Non-class (global) functions can be implemented when they are declared:
<programlisting>function do_global_stuff() {
print "I'm doing stuff!";
}</programlisting></para>
<para>Class functions (methods) must first be declared within the class they will
apply to, and can then be implemented outside the class declaration as follows:
<programlisting>function SomeClass::do_stuff() {
print "I'm doing stuff!";
}</programlisting></para>
<para>It is not permitted to implement a <literal>builtin</literal> function. These
will instead be mapped onto some code written in the host language in the S2
backend.</para>
<para>Layouts are allowed to add new methods to a class without pre-declaration,
but with a few special constraints. Firstly, the method must be declared and
implemented before it is used. Secondly, the method name must begin with
<literal>lay_</literal>, to avoid problems in the future when new methods
may be added to the core layer with the same name.</para>
</section>
<section id='&s2.idroot;langref.functions.calling'>
<title>Calling</title>
<para>Functions outside classes can be called using the following syntax:</para>
<programlisting>dostuff();
dostuff(5);</programlisting>
<para>Functions in classes are envoked from an instance of the class as follows:</para>
<programlisting>$thingy->dostuff(45,"boink");</programlisting>
<para>Note that the parentheses <emphasis>are</emphasis> required when envoking a function.</para>
</section>
</section>
<section id='&s2.idroot;langref.layerinfo'>
<title><varname>layerinfo</varname> declarations</title>
<para>You can use the <varname>layerinfo</varname> declaration to set arbitrary meta-data for a layer. However, certain meta-data keys and values are required for each type of layer.</para>
<para>The syntax of <varname>layerinfo</varname> is:</para>
<programlisting><![CDATA["layerinfo" <Text> "=" <Text> ";"
<Text> ::= <identifier> | <string literal> | <integer literal>]]></programlisting>
<para>At minimum, all that's required to create a valid layer is one layerinfo declaration with name "type", stating the type of the layer. Depending on the layer type, more declarations may be required. Valid types are those listed in the Layers section.</para>
<para>Example:</para>
<programlisting><![CDATA[layerinfo type = theme;
layerinfo name = "Polka-dotted yellow sunrise";
layerinfo author_name = "Jon Doe";
layerinfo author_email = "jondoe@email.addr";
layerinfo des = "A beautiful polka-dotted yellow sunrise with lots of yellow & orange.";
set bgcolor = "#ffff00";
set fgcolor = "#ffc000";]]></programlisting>
<section id="&s2.idroot;langref.layerinfo.keys">
<title>Keys</title>
<section id="&s2.idroot;langref.layerinfo.keys.required">
<title>Required Keys</title>
<informaltable frame='none'>
<tgroup cols='2'>
<tbody>
<row><entry><literal>type</literal></entry><entry>The layer type identifier</entry></row>
<row><entry><literal>majorversion</literal></entry><entry>Required for core layers only</entry></row>
<row><entry><literal>langcode</literal></entry><entry>Language being configured. I18n and i18nc layers only.</entry></row>
</tbody>
</tgroup>
</informaltable>
</section>
<section id="&s2.idroot;langref.layerinfo.keys.recommended">
<title>Recommended Keys</title>
<informaltable frame='none'>
<tgroup cols='2'>
<tbody>
<row><entry><literal>name</literal></entry><entry>The name of the layer to be displayed in the interface.</entry></row>
</tbody>
</tgroup>
</informaltable>
</section>
<section id="&s2.idroot;langref.layerinfo.keys.other">
<title>Other Supported Keys</title>
<informaltable frame='none'>
<tgroup cols='2'>
<tbody>
<row><entry><literal>des</literal></entry><entry>A longer description of the layer.</entry></row>
<row><entry><literal>author_name</literal></entry><entry>The name of the author.</entry></row>
<row><entry><literal>author_email</literal></entry><entry>The email address of the author.</entry></row>
<row><entry><literal>source_viewable</literal></entry><entry>Source of the layer is available to all users on the host site.</entry></row>
<row><entry><literal>is_public</literal></entry><entry>Allow users on the host site to use layers from other users in their styles.</entry></row>
</tbody>
</tgroup>
</informaltable>
<note>
<para>The email address, if given, will likely be displayed on the host site in clear-text.
You should probably leave it out if you are concerned about email-address collecting
software and spam.</para>
</note>
</section>
</section>
</section>
<section id='&s2.idroot;langref.properties'>
<title>Properties</title>
<para>Properties are single values which are exposed by the core and layout layers and set in
all subsequent layers to configure aspects of a style. Properties can be of any primitive
type as well as any class which provides both an <function>as_string()</function> function
which returns a string representation of its data and a constructor function named after
the class which accepts a <parameter>string</parameter> as a parameter and returns an object
based on that string.</para>
<para>The purpose of properties is to expose certain configuration settings of a style
such that they can be set from a friendly <quote>wizard</quote>-like interface.</para>
<section id='&s2.idroot;langref.properties.declaration'>
<title>Declaration</title>
<para>Properties are defined using the following syntax:</para>
<programlisting>property int page_recent_items {
des = "Number of journal entries to show on recent entry page";
min = 5;
max = 50;
}</programlisting>
<para>The key and value pairs within the braces are known as <emphasis>attributes</emphasis>.
These are used by the host application for various uses, including the presentation of a
friendly customization interface.</para>
<section id='&s2.idroot;langref.properties.standard'>
<title>Standard Properties</title>
<para>The following attributes are available for all properties:</para>
<variablelist>
<varlistentry>
<term><varname>des</varname></term>
<listitem><simpara><emphasis role="bold">Required</emphasis> - A textual description of this property.</simpara></listitem>
</varlistentry>
<varlistentry>
<term><varname>values</varname></term>
<listitem><simpara>A string setting the acceptable values of this property, along with a natural language description of each, in the format <literal>"value1|Description1|value2|Description2"</literal> and so on.</simpara></listitem>
</varlistentry>
<varlistentry>
<term><varname>example</varname></term>
<listitem><simpara>An example of what might be put in this field. Can be used when it's not obvious what the value should look like.</simpara></listitem>
</varlistentry>
<varlistentry>
<term><varname>note</varname></term>
<listitem><simpara>A note to be displayed with the field to enter this value.</simpara></listitem>
</varlistentry>
<varlistentry>
<term><varname>noui</varname></term>
<listitem><simpara>Suppresses the display of this property in the editing GUI.</simpara></listitem>
</varlistentry>
</variablelist>
<para>There are also attributes only available for specific types of property, as described
in the following sections.</para>
<section id='&s2.idroot;langref.properties.standard.integer'>
<title>Attributes for integer properties</title>
<variablelist>
<varlistentry>
<term><varname>max</varname></term>
<listitem><simpara>The maximum value permitted.</simpara></listitem>
</varlistentry>
<varlistentry>
<term><varname>min</varname></term>
<listitem><simpara>The minimum value permitted.</simpara></listitem>
</varlistentry>
</variablelist>
</section>
<section id='&s2.idroot;langref.properties.standard.string'>
<title>Attributes for string properties</title>
<variablelist>
<varlistentry>
<term><varname>maxlength</varname></term>
<listitem><simpara>The maximum amount of characters this property can contain.</simpara></listitem>
</varlistentry>
<varlistentry>
<term><varname>size</varname></term>
<listitem><simpara>The size (in characters) of text widget which should be used to set this property from an interface.</simpara></listitem>
</varlistentry>
</variablelist>
</section>
</section>
</section>
<section id='&s2.idroot;langref.properties.set'>
<title>Setting</title>
<para>The <function>set</function> command is used to set the values of properties from all layers:</para>
<programlisting>set text_read_comment = "Read 1 comment";</programlisting>
<para>The value set by the highest layer will be used.</para>
</section>
<section id='&s2.idroot;langref.properties.use'>
<title>Use</title>
<para>In order to use a property from the core layer in a layout, you should first tell the system that you are going to use it. This makes it appear in the customization UI if applicable.</para>
<programlisting>property use property_name;</programlisting>
<para>All layers can use properties as variables as described in the variables section above:</para>
<programlisting>print $*property_name;</programlisting>
</section>
</section>
<section id='&s2.idroot;langref.docstrings'>
<title>DocStrings</title>
<para>You can add short documentation strings to your classes, methods, data members and functions by placing them in quotes inside the declaration, like so:</para>
<programlisting>class Example "An example class" {
var string some_string "An example data member";
function some_method() : int "An example method";
}
function some_function() "An example global function";</programlisting>
<para>These are made available to the S2 backend support code, and applications may provide some kind of documentation browsing facility or the ability to generate static files containing documentation.</para>
</section>

154
wcmtools/s2/doc/docbook/layers.xml Executable file
View File

@@ -0,0 +1,154 @@
<title>Layer Types</title>
<para>As previously mentioned, there are 6 layers types in S2:</para>
<programlisting><![CDATA[
=> core
=> i18nc
=> layout
=> i18n
=> theme
=> user
]]></programlisting>
<para>The hierarchy above indicates which layer types are specific to which others. For example, any given i18n, theme, or user layer is specific to a certain layout. You can't have a theme which works with any layout, since the theme is tied to that layout.</para>
<para>Layouts are tied to a core, but since there's at present only 1 core layer, a layout can pretty much be thought of as the top layer. If in the future it becomes apparent that design mistakes were made at the core layer we can then make a new core layer and support both. Layouts will then be able to be written to any version of the core.</para>
<variablelist>
<varlistentry>
<term>Core Layer (core)</term>
<listitem><para>The core layer defines the classes of objects which will be provided to the S2 code by the web application. Further, it defines the methods on those objects and useful global functions.</para>
<para>Only the core layer can define builtin functions and methods, where the implementation isn't in S2, but implemented by the host web application. Users cannot create new core layers. More than likely, there will only be one core layer on the system. However, the core layer is versioned in case the web application changes drastically and needs a new core layer. In that case, multiple core layers can exist at the same time, and it's the web application's job to check the version number on the core layer in use and provide the right data structures to it.</para>
<para>The core also provides basic implementations for everything, in case other layers don't override them. One major advantage of this is that it makes it extremely easy for LiveJournal to add more view types in the future and have them be compatible with all existing layers: since those layers wouldn't know how to generate a "FooPage", they'll just inherit the FooPage from the core. (Inheritance note)</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Core Internationalization Layer (i18nc)</term>
<listitem><para>The i18nc layer overrides text properties in the core, translating them into a specific language. It also overrides the default short, medium, and long date and time formats and functions which do things like return ordinal numbers from cardinal numbers and map item counts onto their plural form.</para>
<para>
The core layer should have properties for every textual string which will likely be used by more than one layout to minimize the amount of work required by translators. Because the i18nc layer overrides the core, and not specific layouts, all layouts can take advantage of things defined in the core and i18nc layers.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Layout Layer (layout)</term>
<listitem><para>A layout is the largest and most involved layer type developers will create. A layout defines the look &amp; feel of the journal and provides all the properties which the three child layers have access to modify.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Layout Internationalization Layer (i18n)</term>
<listitem><para>An i18n layer is like i18nc, but it's specific to a layout.</para>
<para>If a layout introduces new textual or locale-specific properties/functions because it couldn't use stuff already in the core, an i18n layer overrides just those new items. The fact that there are two i18n layers is hidden from the user... they just select "Deutsch" (or it's selected by default automatically, based on their browser settings) and the system picks the i18nc and i18n layers which match the "de" language code for their layout and core. (their core layer is also automatically selected if there are more than one, based on the layout they choose)</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Theme Layer (theme)</term>
<listitem><para>A theme layer overrides color, image, font, and sound properties provided in the layout (some of which the layout may simply pass on from the core).</para>
</listitem>
</varlistentry>
<varlistentry>
<term>User Layer (user)</term>
<listitem><para>A user layer tweaks any last properties. A graphical wizard on the site auto-generates this after showing the end-user all the available properties. Everything is incredibly simple: colors are picked using a color-picker widget, for example.</para>
</listitem>
</varlistentry>
</variablelist>
<section id='&s2.idroot;layers.caps'>
<title>Layer Capabilities</title>
<para>The following table summarizes what each layer type is permitted to do:</para>
<informaltable frame='all'>
<tgroup cols='7' align='center' colsep='1' rowsep='1'>
<colspec align="left" />
<thead>
<row>
<entry></entry>
<entry>core</entry>
<entry>i18nc</entry>
<entry>layout</entry>
<entry>i18n</entry>
<entry>theme</entry>
<entry>user</entry>
</row>
</thead>
<tbody>
<row>
<entry>Define classes</entry>
<entry>X</entry>
<entry />
<entry />
<entry />
<entry />
<entry />
</row>
<row>
<entry>Define <function>builtin</function> functions/methods</entry>
<entry>X</entry>
<entry />
<entry />
<entry />
<entry />
<entry />
</row>
<row>
<entry>Define global functions</entry>
<entry>X</entry>
<entry />
<entry>X</entry>
<entry />
<entry />
<entry />
</row>
<row>
<entry>Define class methods</entry>
<entry>X</entry>
<entry />
<entry>X<footnote><para>
Layouts adding methods to classes must prefix the method name with <function>lay_</function> to avoid future namespace collisions should the core layer expand.</para></footnote></entry>
<entry />
<entry />
<entry />
</row>
<row>
<entry>Define properties</entry>
<entry>X</entry>
<entry />
<entry>X</entry>
<entry />
<entry />
<entry />
</row>
<row>
<entry>Expose properties to graphical wizard</entry>
<entry />
<entry />
<entry>X</entry>
<entry />
<entry />
<entry />
</row>
<row>
<entry>Override name/description of properties</entry>
<entry>-</entry>
<entry>X</entry>
<entry>X</entry>
<entry>X</entry>
<entry />
<entry />
</row>
<row>
<entry>Override functions/methods</entry>
<entry>-</entry>
<entry>X</entry>
<entry>X</entry>
<entry>X</entry>
<entry>X</entry>
<entry />
</row>
<row>
<entry>Set properties</entry>
<entry>X</entry>
<entry>X</entry>
<entry>X</entry>
<entry>X</entry>
<entry>X</entry>
<entry>X</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</section>

8
wcmtools/s2/doc/docbook/misc.xml Executable file
View File

@@ -0,0 +1,8 @@
<title>Misc</title>
<section id='&s2.idroot;misc.inheritance'>
<title>Inheritance: object inheritance vs. layer inheritance</title>
<para>You might've read about layout inheritance (things not defined in a layout inherit from the core, for example) and read about the more familiar object inheritance (an undefined method <function>Poodle::bark()</function> inherits from <function>Dog::bark()</function>) and asked yourself&hellip;</para>
<para><emphasis>"How do object inheritance and layer inheritance interact? Which comes first?"</emphasis></para>
<para>Object inheritance happens first and is saved into the layer. At the very end, when layers are combined to make a vtable for a style, that's when layer inheritance happens.</para>
<para>If none of this makes sense, don't worry about it.</para>
</section>

29
wcmtools/s2/doc/docbook/notes.txt Executable file
View File

@@ -0,0 +1,29 @@
----------------
S2 Manual Notes:
----------------
Build:
------
The source to this manual is straight DocBook, with no extra compilation required
beforehand, unlike the LiveJournal and FotoBilder manuals. For our projects we use
libxslt to parse, validate, and compile the manuals, and Debian as our OS of choice.
To compile the docs for yourself on Debian, you need the following packages:
* xsltproc
* docbook-xml
* docbook-xsl-stylesheets
The command we use is 'xsltproc', like so:
xsltproc --nonet --catalogs docbook-xsl-stylesheets/html/chunk.xsl index.xml
Semantics:
----------
The common DocBook elements we use are:
classname
inline, names of S2 classes
methodname
inline, names of S2 class methods
function
inline, names of global functions
varname
inline, names of misc variables
TODO: explain the merging process for the LJ and FB manuals

10
wcmtools/s2/doc/docbook/notes.xml Executable file
View File

@@ -0,0 +1,10 @@
<title>Tech Notes</title>
<section id='&s2.idroot;how'>
&s2.how;
</section>
<section id='&s2.idroot;caveats'>
&s2.caveats;
</section>
<section id='&s2.idroot;misc'>
&s2.misc;
</section>

7
wcmtools/s2/doc/docbook/overview.xml Executable file
View File

@@ -0,0 +1,7 @@
<title>Overview</title>
<section id='&s2.idroot;terms'>
&s2.terms;
</section>
<section id='&s2.idroot;layers'>
&s2.layers;
</section>

10
wcmtools/s2/doc/docbook/preface.xml Executable file
View File

@@ -0,0 +1,10 @@
<title>Introduction</title>
<section id='&s2.idroot;about'>
&s2.about;
</section>
<section id='&s2.idroot;history'>
&s2.history;
</section>
<section id='&s2.idroot;design'>
&s2.design;
</section>

24
wcmtools/s2/doc/docbook/terms.xml Executable file
View File

@@ -0,0 +1,24 @@
<title>Terminology</title>
<para>S2 uses different terminology than S1. Here's a quick overview:</para>
<variablelist>
<varlistentry>
<term>layer</term>
<listitem><simpara>There are 6 layer types in S2, each providing and/or overriding certain types of functions &amp; properties. These include: core (the base), i18nc (internationalization for the core), layout, i18n, theme, and user.</simpara></listitem>
</varlistentry>
<varlistentry>
<term>style</term>
<listitem><simpara>A style is a set of 1-6 layers. At minimum a style includes a core layer (at present, there's only one) and can contain 0 or 1 of each other layer type. The only options for a style (outside of its layers) are its name and whether it's public or not.</simpara></listitem>
</varlistentry>
<varlistentry>
<term>layout</term>
<listitem><simpara>A layout is the most important &amp; influential of the different layer types, excluding the core which is built-in and users can't create or modify. The layout defines the look and feel of the style. The other layers just tweak the layout. A layout layer is roughly analagous to an S1 style.</simpara></listitem>
</varlistentry>
<varlistentry>
<term>property</term>
<listitem><simpara>Both core and layout layers can define properties which the end-user can modify using a graphical wizard. When defining a property you define its datatype, optional min/max values, set of possible values for a drop-down, widget type to offer, etc..</simpara></listitem>
</varlistentry>
<varlistentry>
<term>constructional property</term>
<listitem><simpara>The core layer defines some properties which are recognized by the system and inspected prior to constructing the data structure which S2 code is given. The global function prop_init(), optionally implemented by the layout layer, is responsible for setting the constructional properties if it's inappropriate to expose them directly to the user, or if they need to be setup based upon other properties the user did choose. The constructional properties are indicated in the core layer documentation.</simpara></listitem>
</varlistentry>
</variablelist>

145
wcmtools/s2/doc/grammar.txt Executable file
View File

@@ -0,0 +1,145 @@
LEXICAL SPECIFICATION (Tokenizer.java)
============================================================================
string := "([^\\]|\\.)*?" | """([^\\]|\\.)*?"""
Either a "quoted string with \" \\ escaping" or:
"""tripled quoted strings, which allow "quotes" inside them"""
Both types of quoting allow interpolation of variables, so
$ signs must be escaped when meant literally.
ident := [a-zA-Z_] [a-zA-Z0-9_]*
integer := [0-9]+
VarRef := "$" ("."|"*")? ident ( "." ident )* |
"${" ("."|"*")? ident ( "." ident )* "}"
ws := [ \n\t\r]+
doublecolon := "::"
NativeType := "bool" | "string" | "int"
DocString := <TokenStringLiteral>
GRAMMAR
============================================================================
Layer.java:
-------------------------
Layer := <LayerContents>*
LayerContents := LayerInfo | ClassDecl | FuncDecl | FuncDef |
Prop | Set
NodeLayerInfo.java
-------------------------
LayerInfo := "layerinfo" <Text> "=" <Text> ";"
NodeText.java
-------------------------
Text := <ident> | <string> | <integer>
NodeClass.java
-------------------------
ClassDecl := "class" <ident>
( "extends" <ident> )?
<StringLiteral>?
"{" ClassItemDecl* "}"
ClassItemDecl := ClassVarDecl | FuncDecl
ClassVarDecl := "var" <NamedType> DocString? ";"
NodeProperty.java
-------------------------
Prop := "property" "builtin" Type ident ";"
|
"property" Type ident "{" <PropertyPair>* "}"
|
"property" ("use" | "hide") Type ";"
NodePropertyPair.java
-------------------------
PropertyPair := <Text> "=" <Text> ";"
NodeSet.java
-------------------------
Set := "set" <Text> "=" <Text> ";"
NodeFunction.java
-------------------------
FuncReturn := ":" <SimpleType>
FuncDecl := "function" "builtin"? <ident> FuncArgs? FuncReturn? DocString? ";"
FuncArgs := "(" FuncArgItem ("," FuncArgItem)* ")"
FuncArgItem := <Type> <ident>
FuncDef := "function" (<ident> "::")? <ident> FuncArgs? FuncReturn? DocString? <StmtBlock>
VarDeclStmt := "var" <Type> <ident> ";"
Expr := <AssignExpr>
AssignExpr := <CondExpr> ({"="} <AssignExpr>)?
CondExpr := <LogOrExpr> ("?" <LogOrExpr> ":" <LogOrExpr>)
LogOrExpr := <LogAndExpr> ({"or"|"xor"} <LogAndExpr>)?
LogAndExpr := <EqualExpr> ("and" <EqualExpr>)?
EqualExpr := <RelationExpr> ({"=="|"!="} <RelationExpr>)?
RelationExpr := <SumExpr> ({"<"|"<="|">"|">="} <SumExpr>)?
SumExpr := <MultExpr> ({"+"|"-"} <MultExpr>)?
MultExpr := <UnaryExpr> ({"*"|"/"|"%"} <UnaryExpr>)?
UnaryNegation = {"not"|"-"}? <IncExpr>
IncExpr = <Term> {"--"|"++"} |
{"--"|"++"} <Term> |
<Term>
Term := <integer> | <string> | VarRef | ParenExpr | CallExpr
ParenExpr := "(" <Expr> ")"
CallExpr := <ident> "(" ArgList ")"
ArgList := (Expr ("," Expr)*)?
Type := SimpleType ("[]"|"{}")*
StmtBlock := "{" Stmt* "}"
Stmt := PrintStmt | IfStmt | ForeachStmt
PrintStmt := {"print" | "println"} <Expr> ";"
ForeachVarDecl = "var" <SimpleType> <LocalVarRef>
ForeachStmt := "foreach" { <LocalVarRef> | <ForeachVarDecl> }
"(" <Expr> ")" <StmtBlock>
IfStmt := "if" "(" <Expr> ")" <StmtBlock>
( "elseif" <StmtBlock> )*
( "else" <StmtBlock> )?

45
wcmtools/s2/doc/language.txt Executable file
View File

@@ -0,0 +1,45 @@
variable interpolation in strings:
==================================
"foo" -> ("foo")
"hi $name" is expanded -> ("hi " + $name)
"my name is ${name}athon" -> ("my name is " + $name + "athon")
NOTE: extra tokens for parens and opt. plus signs
typing:
=======
strong typing.
casting functions builtin.
class declarations:
===================
only allowed in the core.
they could be allowed in the layout layer as well, but then there are problems:
- need syntax to create objects at run-time
- class namespace (what if we add a new class to the core later?)
- little need, anyway.
function declarations:
=====================
function declarations inside class declarations (method declations)
are only declarations. since class declarations can only be in the
core, so can declarations of new methods.
function declarations outside classes are either:
1) empty (no StmtBlock). look like C prototypes. this implies the
function is built-in (defined in s2builtin.pl). only allowed in
core.
2) defined, with body. allowed in all layers, with the following
restrictions:
- can only override existing functions in theme, i18n, user
layers
- free users can only define 1 or 2 functions in their user
layer, though they can define all available properties.

33
wcmtools/s2/doc/layerinfo.txt Executable file
View File

@@ -0,0 +1,33 @@
The layerinfo keys & values can for the most part be whatever you want.
However, some are either required or recommended:
REQUIRED:
type = must be core, i18nc, layout, theme, i18n, or user.
name = shown in selection on the website.
majorversion = all core layers must have integer majorversion. see versioning.txt
RECOMMENDED:
author_name
author_email
des = description
MAGIC:
redist_uniq = When layers are redistributed, they need a uniqname
that never changes so they can be found and upgraded on
any installation, regardless of that system's system
account userid and s2lid values. the compiler or web
tool doesn't enforce this. it's just handled by
redist.pl (called by update-db.pl). this value should
have no spaces or funky characters, since it'll be a filename
on disk. that is, it should be in /^\w{1,25}$/
the uniqname should be prefixed by "loc" if it's a site
local layer, so the namespaces don't conflict. this is
just convention, though; not enforced or used in any tools.
scope = used by `redist.pl --write` to decide which system
styles go in redist.dat and which go in redist-local.dat.
by default, scope of system stuff is "general" unless
declared "local"

168
wcmtools/s2/doc/layers.txt Executable file
View File

@@ -0,0 +1,168 @@
S2 Layers
=========
A style in the S2 system is comprised of a number of layers stacked on
top of each other. Layers serve different purposes and can add or
change different things at each step. End-users pick and choose which
layers they want and that ultimate determines how their journal looks.
The layers from the bottom to top are:
Built-in
Core
I18n-C
Layout
I18n
Theme
User
0: BUILT-IN
===========
This is a very thin layer that can almost be considered part of the
core layer (layer 1), but it has on large difference: the
implementation of the built-in layer is done in the S2 system's
backend language. In this initial implementation, this is Perl. This
layer serves as the bridge between reality and the happy opaque world
that is S2. It lets S2 code have access to get data from the outside
and do things that are either available in native S2, or explicitly
disallowed because they could be unsafe.
1: CORE
=======
The core defines all the classes that are available in the system.
This definition includes both the data structures available to higher
layers and default implementations. That is, it defines everything
there is available in, say, a journal entry object, and also defines
how to dump it to HTML.
Overtime as more functionality is added to LJ, the number of these
classes will grow, but it must never shrink or change, as to preserve
compatability with old layers above it. Classes exist to represent
common LJ objects (journal entries, users, page views, etc.).
The cool thing about having default implementations in this layer is
that they're inherited by higher layers, including old ones written
when the core layer was smaller. This lets us add new view types
(Memories view, Userinfo view, etc...) and have them match the user's
layout, without any of the layer authors updating their code.
There is only one core layer so users can't select it. (well, see
versioning.txt) The core layer defines what's available in the
built-in layer, so obviously users can't select their built-in layer
either. In fact, the existence of a built-in layer is transparent to
most parts of the system.
2: LAYOUT
=========
The layout is what in S1 we called a style. In S2 terminology, the
style is the end result of combining all your layers together. The
layout layer defines the most basic customizable element of the S2
system... it determines the base look for the style. If a user wanted
to change their journal to match a very explcit look (say, to match an
existing website of theirs), then they'd make a new layout layer. LJ
will provide a half-dozen of these, but the real customizabilty in the
new system is in the upper layers.
All layers can overide functions and properties in lower layers, but a
layout layer is unique in that it can define new functions and
properties.
3: THEME
========
In S1, a color theme was a top-level entity, just like a style. The
idea was that style authors should be careful in designing their
styles using the right color codes such that any color theme could be
applied to it and the result would be pleasing. This required a lot
of effort on the part of both style authors and color theme authors,
so it ultimately failed. Lots of fingers were pointed between the two
groups and finally I admitted I was wrong in designing a system that
relied on everybody understanding such concepts. Once one person made
a misbehaving style or theme, it pretty much ruined the entire system,
as nobody cared from that point on.
The result is that we were left with the obscure notion of "color
codes" which were impossible for users to imagine how to map onto the
style (now: layout) they were looking at. They'd eventually discover
that "light emphasis text 2" meant, "the color at the top in the box".
In S2, themes are tied to layouts, and the layout layer defines that
properties can be overridden (these include color codes). That way a
theme will fit a layout very closely. Also, themes can define any
properties that a layout layer reflects, which might include images
and sound (I hate cheesy MIDIs... before sound will be allowed, there
will be a visitor option to disable ever hearing any sound).
Themes will rule.
4: I18N
=======
The next layer up is i18n (Internationalization). Functionally, an
i18n layer as all the same power as a theme layer, but they serve
different purposes. Whereas a theme layer will be overriding
properties and methods that affect colors and graphics, an i18n layer
will override a different subset that affects the text.
An i18n layer is specific to a layout, not a layout+theme. We can
hopefully expect translators to produce 5 or 6 i18n layers (one per
layout), but we can't expect them to produce 120 (6 times, say, 20
themes per layout).
This then raises the question -- what if the i18n layer and theme
layer override an overlapping set of functions or properties? If the
layout layer is designed to abstract copy and style in all the right
places, then this won't be a problem. This isn't actually very hard
to do, and once we show users how it's done, they'll be able to write
compliant layout layers. Only compliant layouts will be publicly
available to users, so even if a user does make their own terribly
non-compliant layout, chances are they're not interested in having it
translated anyway.
5: USER
=======
The final layer is the user layer. Few users will likely use this,
but it provides a way to tweak anything that the lower layers didn't do
to the journal owner's pleasing. This is equivalent to the S1
"overrides" box, but will be a lot simpler. The user will be able to
make this layer with a wizard as well, or type in S2 code manually if
they so please.
SUMMARY
=======
In summary, the layers are:
Built-in -- bridge to real world
Core -- defines what layers can access & do
I18n-C -- internationalization that applies to the core
Layout -- an S1 "style", but see note below.
i18n \
Theme - Tweaking a layout.
User /
Although we called a layout a "style" in S1, in S2 we're going to be
calling a layout a layout and we'll only use "style" to describe the
end result of all a user's layers together.
CAPABILITIES:
=============
Declaring classes: core
Declaring new functions: core, layout
Declaring properties: core, layout
Changing "des" property on properties: i18n

14
wcmtools/s2/doc/overview.txt Executable file
View File

@@ -0,0 +1,14 @@
Overview of S2:
===============
This is the overview file for S2, or "LiveJournal, Style System,
version 2". See the documents referenced below for more details of
different aspects of the S2 system.
Design goals: design_goals.txt.
Layers: layers.txt.
Language: language.txt

33
wcmtools/s2/doc/properties.txt Executable file
View File

@@ -0,0 +1,33 @@
properties can be either strings or integers (or of type Color)
attributes on properties:
Required for all types:
des = description of property (short)
Optional for all types:
values = acceptable values with accompanying descriptions in form
join("|", "value|des"), like "1|One|2|Two"
example = example value to be shown in italics when it's not obvious what
the value should be like.
paidonly = need a paid account to set this property, otherwise default.
note = further note explaining the property
Optional for type 'int':
max -- maximum value for the int
min -- minimum value for the int
Optional for type 'string':
maxlength -- max length of string
size -- size of text widget to show
Built-in:
name -- the variable name is included in the hash. the API adds
this virtual attribute.

17
wcmtools/s2/doc/versioning.txt Executable file
View File

@@ -0,0 +1,17 @@
If it ever becomes necessary to scrap the entire core layer because of
a design flaw that's too difficult to work around, here's the
solution that provides a clean upgrade path:
-- insert a new s2layers row with a type of 'core' and a b2lid
of 0, like the existing core layer. but all core layers are
required to have a 'majorversion' layerinfo field.
-- make the /customize/ UI let people pick in the layer drop down
not just layers, but core+layer combos that work, labeled with
their major versions, so people will prefer higher ones.
-- the ljviews code that gives the data structure to S2 runner will
have to know which version the S2 code is expecting, and do the
right thing, based on the core layer's 'majorversion' data.
-- the S2 Builtin layer has to be a superset every version higher.