Част от информацията в тази страница може да не е актуална.

Subversion хранилище на проекта

Целият код на проекта е достъпен за четене през Subversion. Адресът на хранилището е http://triangle.bg/svn/trunk/triangle.bg.

Разглеждането на хранилището през браузър е възможно чрез системата Trac.

Необходим софтуер за образуване на сайт от необработените беседи

Всички необходими програми са свободен софтуер. Засега генерирането на съдържанието на сайта може да стане само върху операционната система Линукс, като се предполага стандартна инсталация. Програмите, които евентуално трябва да се сложат допълнително, са:

  • xsltproc, версия 1.0.30 или по-нова
  • GNU Make, версия 3.81 или по-нова (3.81 все още е в бета)
  • GNU Fileutils, версия 4.1 или по-нова
  • GNU tar, версия 1.13 или по-нова
  • GNU Bash, версия 2.05 или по-нова
  • bzip2
  • Perl 5.8 със следните допълнителни модули:
    • XML::LibXML

Общ поглед към библиотеката

Основните единици са беседите. Конкретните издания се съхраняват като XHTML файлове в директорията на съответното издание на книга и пълното име изглежда така: books/КНИГА/БЕСЕДА.xhtml. В самите файлове няма никаква информация за връзката на тази беседа с другите, като например в коя книга се намира. Тази мета-информация се съдържа във файла book.xml на книгата. Това е направено, за да могат файловете с текстовете да бъдат максимално изчистени.

Организирането на беседите в книга се описва във файла book.xml в директорията на книгата. В него се съдържа списък на беседите, както и разнообразна информация за конкретното издание. Списъкът на книгите се намира във books/books.xml. Там те са разделени и на класове: неделни, утринни и т.н.

Чакащите включване в сайта книги, например тези от диска на Хелиопол, са в директорията raw, като тяхното описание се намира във файла raw.xml.

Цялото конструиране на сайта се извършва от Makefile. За да компилирате всичко, просто изпълнете командата make в директорията на библиотеката. Това създава сайт в поддиректорията www, като се използва поддиректорията tmp като временно място. Ако искате сайтът да се построи в друга директория, използвайте команда от вида make htmldir=директория, където директория е пътят до тази друга директория.

Правила за файловете с беседи

За да могат текстовете да бъдат в максимално удобен за машинна обработка вид, те се съхраняват в формата XHTML Basic. Накратко, това е предефиниране на HTML 4.01, което го превръща и в XML 1.0, като XHTML Basic изчистен от много остарели и/или усложнени конструкции. Именно използването на XML позволява на текстовете максимално лесно да бъдат обработвани автоматизирано, а използването на HTML позволява това да се прави лесно и бързо от човек, тъй като този език се познава от всеки, който би се заел с такава задача.

Обща структура на текст

Общата структура на текст изглежда по следния начин:

<?xml version="1.0"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML Basic 1.0//EN"
"http://www.w3.org/TR/xhtml-basic/xhtml-basic10.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="bg">

<head>
<title>Заглавие</title>
</head>

<body>

Съдържание

</body>

</html>

(За удобство при четенето имената на HTML елементите са маркирани с удебеляване на буквите.)

Първият ред е задължителен маркер, показващ че това е XML файл. Явно се задава и кодирането на файла, което по подразбиране е UTF-8. Използва се windows-1251 вместо UTF-8 заради по-малкото място, което се заема.

Вторият и третият ред явно задават, че това е XHTML Basic 1.0 документ. Тази декларация е незадължителна, но тя може да бъде много полезна при различни обработки на текста, гарантирайки че ще се следват стриктно правилата на XHTML Basic 1.0 за документи.

По-нататък виждаме познатата структура на HTML файловете. Атрибутите на елемента html са задължителни за XHTML Basic 1.0. Единственото по-особено нещо е липсата на елемент meta, който да зададе кодирането на документа. Тази роля в случая се изпълнява от първия ред, който вече е задал кодирането. Заглавието не се повтаря като h1 елемент в началото на съдържанието. Това е напълно излишно за документ, който не е предназначен да бъде гледан направо, без никаква обработка.

Специфични стилови описания

XHTML Basic 1.0 не позволява вградени стилови описания и затова ако се налагат такива, те се съхраняват във външен файл. Той има същото име, но с разширение .css вместо .xhtml. CSS 1 е предпочитан, но при нужда се използва CSS 2.1. Добавен е и следният ред в <head>:

<link rel="stylesheet" type="text/css" href="файл.css" />

Фигури

Фигурите са във външни файлове във формат SVG 1.1 Tiny, който впоследствие се превръща в PNG. Името на файла се образува от името на XHTML файла, и _figНОМЕР.svg. Връзката в XHTML файла изглежда така:

<span class="figure left-aligned">
<object type="image/svg+xml" data="1919-11-16-10_fig1.svg" />
<span class="caption">Фиг. НОМЕР</span>
</span>

Вместо left-aligned може да има още right-aligned и inline. Размерът се определя от viewBox на самия файл. При използване на <p> вместо на <span> класът трябва да е само figure и фигурата се показва центрирана:

<p class="figure">
<object type="image/svg+xml" data="идентификатор_figНОМЕР.svg" />
<span class="caption">Фиг. НОМЕР</span>
</p>

Шаблонът на SVG-файловете е следният:

<?xml version="1.0" encoding="UTF-8"?>  <!-- -*- coding: utf-8 -*- -->
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" 
         "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
<svg xmlns="http://www.w3.org/2000/svg"
  version="1.1" baseProfile="tiny"
  viewBox="0 0 ширина височина">

  <g font-family="sans-serif" fill="none"
    stroke="currentColor" stroke-width="4"
    stroke-linecap="round" stroke-linejoin="round">
...

    <g fill="currentColor" font-size="големина" stroke-width="1">
      <text...>...</text>
    </g>

...
  </g>

</svg>

Широчината, височината, както и всички числови единици във векторната графика, се измерват спрямо сканирано изображение при 300 dpi.

Използвани XHTML елементи

В термините на Modularization of XHTML използваните абстрактни модули и елементите в тях са изброени по-долу. Това е съкратен начин за представяне на XHTML Basic 1.0.

  • Модул за структура (Structure Module): body, head, html, title.
  • Модул за текст (Text Module): blockquote, div, p, em, q, span, strong.
  • Модул за свързан текст (Hypertext Module): a.
  • Модул за списъци (List Module): dl, dt, dd, ol, ul, li.
  • Модул за прости таблици (Basic Tables Module): caption, table, td, th, tr.
  • Модул за вграждане на обекти (Object Module): object, param.
  • Модул за метаинформация (Metainformation Module): meta. (Засега не се използва в никой от текстовете.)
  • Модул за свързване (Link Module): link.

Повече от тези елементи не би трябвало да е нужно да присъстват. Засега няма начин да се поставят изображения, но в бъдеще ще се използва SVG (Scalable Vector Graphics), като описанието на графиката се включва направо в документа. Също забележете, че не трябва да има никакви явни задавания на стилове (stylesheets) или мета-информация коя е следващата беседа например.

Специфични правила за текстовете

В текстовете на беседите елементите на модула за текст трябва да се използват по точно определен начин, за да могат да добавят определен смисъл на частите от текст. Това се нарича микроформат. Ето конструкциите, които трябва да се използват:

<p>текст</p>
Абзац, разбира се.
<p class="lines">ред<br/>
ред<br/>
ред</p>
(обикновено с други класове) Абзац, в който има принудително преминаване на следващия ред.
<p class="info">текст</p>
<p class="info lines">текст</p>
Допълнителна информация, която може да се използва извън конкретното местоположение в течението на текста, например дата на изнасяне на беседата.
<p class="note">текст</p>
<span class="note">текст</span>
Бележка, която е неотделима от конкретното местоположение в текста, например час в момента или описание на обстановката. <span class="note"> може да се използва в <p class="...">.
<span class="explain">текст</span>
Поясняващ или пропуснат текст. class="explain" е частен случай на class="note".
<p class="act">текст</p>
<span class="act">текст</span>
Действие в потока на текста. class="act" е частен случай на class="note".
<p><br class="hr"/><p>
Хоризонтална линия за отделяне на части от текста.
<p><br class="space"/><p>
Празно пространство между абзаци.
<q>текст</q>
Изговорени мисли и думи на други хора. По правило на края никога не се слага точка, запетая и друга пунктуация, а се слага отвън, даже и ако се цитира изречение. Обаче ако изречението завършва на въпросителна или удивителна, те се пишат вътре в елемента, и веднага след елемента не се пише точка.
<q class="open">текст</q>
<q class="inside">текст</q>
<q class="close">текст</q>
Текст кавички, който е разпрострян на няколко абзаца. class="open" показва само отварящата кавичка, class="inside не показва кавички, а class="close" показва само затварящата кавичка.
<p class="formula">текст</p>
Формула или мото. <p class="formula"> е частен случай на <p class="act">.
<p class="inner">текст</p>
Вътрешно действие на слушателите, например „Т.м.“ или „Размишление“. <p class="inner"> е частен случай на <p class="act">.
<p class="prayer">текст</p>
Произнесена молитва. <p class="prayer"> е частен случай на <p class="act">.
<p class="song">текст</p>
Заглавие на изпята песен. <p class="song"> е частен случай на <p class="act">.
<blockquote class="bible"><p>текст<p></blockquote>
Цитат от Библията в началото на беседата.
<blockquote class="song">
<p class="lines">ред<br />
ред<br />
ред</p>
</blockquote>
Текст на изпята песен.
<q class="writings-subject">текст</q>
<span class="writings-subject">текст</span>
Заглавие на дадена тема.
<q class="writings-subject requested">текст</q>
<span class="writings-subject requested">текст</span>
Даване на тема за писане. (Трябва да има клас и не само за даване, но и за хипотетично даване.)
<q class="song">текст</q>
<span class="song">текст</span>
Заглавие на песен.
<q class="prayer">текст</q>
<span class="prayer">текст</span>
Заглавие на молитва.
<cite class="bible">текст</cite>
Място на текст в Библията (книга, глава, стих). Цитиране на текст от друга книга.
<q class="as-is">текст</q> (още не се използва)
Звук(ове), дума или фраза сама по себе си.
<q class="mnote">текст</q> (още не се използва)
Музикална нота.
<q class="letter">текст</q> (още не се използва)
Буква.
<var>променлива</var>
Използва се за имена на променливи или точки и линии в геометрични построения, например „A не е равно на B“.
<strong>текст</strong>
В оригиналната беседа е разреден текст, който маркира важна мисъл.
<blockquote>текст</blockquote>
Цитиране на откъс от Писанията в началото на беседата. Вътре трябва да се съдържат цитатите в елементи p, като в края на всеки в скоби е написано точното място на цитата.
<span class="act">(текст)</span>
Действие на Учителя по време на беседа. Може да се използва и за отбелязване на нещо, случващо се в околната обстановка.
<span class="listeners">(текст)</span>
Действие или думи на някой присъстващите по време на беседа.
<span class="info">(&#8212; текст)</span>
Допълнителна бележка, като например кой стих е бил цитиран.
class="content" (подразбира се при <blockquote>)
Използва се заедно с друг клас и обозначава, че в елемента има съдържание, а не заглавие.
class="performed" (подразбира се при <p>)
Използва се заедно с друг клас за вид на заглавие и обозначава, че не само заглавието е изговорено, но следва и изпълнение на песента, молитвата и др.
<span class="math">израз</span> (още не се използва)
Математически израз. Между отделните елементи има интервали и стиловите описания забраняват пренасянето. Дроби, самостоятелни променливи и имена на точки и прави също са опаковани в <span class="math">.
<var class="geom">буква</var> (още не се използва)
Геометрическа точка.
<span class="geom">израз</span> (още не се използва)
Геометрически израз, например линия или триъгълник, изразени чрез геометрически точки.
<var class="chem">буква</var> (още не се използва)
Химически елемент.
<span class="chem">формула</span> (още не се използва)
Химическа формула или химическо съединение, съставено от химични елементи.
<p class="time">(текст)</p> (още не се използва)
Текущо време. Частен случай на p.note.
<p class="weather">(текст)</p> (още не се използва)
Метереологично време. Частен случай на p.note.
Текст на препратката
* Заглавие
* Съдържание

Възпроизвеждане?
* Без възпроизвеждане
* С възпроизвеждане

Ако текстът на препратката е съдържание, то е:
* Цитиран текст
* Преразказан текст

Идентификаторът е
* местонахождение (@href или @cite)
* заглавие (@title или text())

Освен изискването да се използват горните елементи, в текста трябва да се използват и следващите специални знаци. Те се задават с числови стойности, защото техните стойности по имена, които по-долу са дадени в скоби, не могат да се разпознаят правилно от някои програми, по специално тази, която се използва за конструиране на сайта (xsltproc).

&#8212; (&mdash;)
Дългото тире се използва в американската граматика, но не и в европейските, включително българската.
&#8211; (&ndash;)
Средно дълго тире, по-дълго от обикновеното, но по-късо от дългото. Използва се за маркиране на отговор в разговор и други цели по правилата на граматиката, както и за задаване на област от стойности, например 1–3.
&#768;
Ударение на предишния знак. Този знак не е самостоятелен, а служи само за да отбележи, че предишният знак трябва да бъде с ударение. По-новите браузъри интерпретират правилно този знак. Най често са използва за ударено „и“ („ѝ“), но може също да прави някои думи еднозначни.

Компилиране

Процесът на компилиране зависи от променливите htmldir, tmpdir и version, които могат да се променят от потребителя. В htmldir се записва компилираният сайт, а в tmpdir – временни файлове. Ето примерно задаване на тези променливи, което в случая задава подразбиращите се стойности:

$ export htmldir=www
$ export tmpdir=tmp
$ export version=$(date +%Y%m%d)   # Днешната дата

Самото компилиране се осъществява чрез удовлетворяване на целта html:

$ make html

Могат да се компилират и само отделни файлове:

$ make $htmldir/index-books.html

Структура на системата за генериране

Makefile-ове

Основният файл, който управлява процеса на генерирането, е Makefile. От своя страна той включва следните генерирани файлове:

  • $(tmpdir)/Makefile-depends
  • $(tmpdir)/Makefile-timeline
  • Makefile-bible

Пълен преглед на генерирането на един HTML файл

  1. $(tmpdir)/%.xml

    Някои от XHTML файловете започват от XML файлове, които се генерират от специфични правила.

  2. $(tmpdir)/%.gen.xhtml

    От XML файловете се генерира неокончателен XHTML файл.

  3. $(tmpdir)/%.xhtml

    От неокончателния XHTML файл се генерира окончателен XHTML файл, обикновено чрез стиловото описание content/link-other.xsl или друго подобен. Промените са най-вече козметични спрямо %.gen.xhtml.

  4. $(stampdir)/%.html

    Това е окончателният HTML файл, образуван обикновено чрез стиловото описание content/document.xsl. Променливата $(stampdir) е обяснена в следващата стъпка.

  5. $(htmldir)/%.html

    Правилото за генериране на $(stampdir)/%.html завършва с макроса $(stamp-cp), който проверява дали файлът в $(stampdir) е различен от този в $(htmldir). Ако е различен, тогава файлът от $(stampdir) се копира в $(htmldir).

    Причината за използване на този подход е за да не се променят времената на промяна в $(htmldir), когато няма промени. Това е важно, когато голям сайт се публикува в Интернет и промяна във времето на последна промяна може да предизвика повторно изтегляне на файл.

Пълен процес на генериране

Пълният процес на генериране протича в следните основни етапи:

  1. Makefile-* файлове
  2. Индексни файлове
  3. „Чисти“ XHTML файлове в tmpdir
  4. Крайни XHTML файлове в stampdir, като при промени те се копират в htmldir.

Основно съдържание на сайта

tmpdir/books/book-id/book.xml
  1. books/book-id/book.xml
  2. (transforms/book-with-titles.xsl)
  3. tmpdir/books/book-id/book.xml
tmpdir/books-ext.xml
  1. books/books.xml
  2. ↓ entities.xml
  3. (transforms/books.xsl)
  4. tmpdir/books.xml
  5. ↓ tmpdir/books/book-id/book.xml (всички книги)
  6. (transforms/books-merge.xsl)
  7. tmpdir/books-with-titles.xml
  8. (transforms/indices-init.xsl)
  9. (transforms/indices-add-simple.xsl)
  10. (transforms/indices-uniq-simple.xsl)
  11. (transforms/indices-fix-simple.xsl)
  12. (transforms/indices-fix-simple-letters.xsl)
  13. tmpdir/indices-simple.xml
  14. (transforms/books-ext.xsl)
  15. tmpdir/books-ext.xml
tmpdir/book-id/index.xhtml (за налични книги)
  1. tmpdir/books-ext.xml
  2. (content/book-html-avail.xsl)
  3. (content/book-html.xsl)
  4. tmpdir/book-id/index.xhtml
  5. tmpdir/book-id/attach-href
  6. tmpdir/book-id/lecture-id.xhtml
  7. tmpdir/book-id/index-all.xhtml
tmpdir/book-id/index.xhtml (за всички неналични книги наведнъж)
  1. tmpdir/books-ext.xml
  2. (content/book-html-notavail.xsl)
  3. (content/book-html.xsl)
  4. tmpdir/book-id/index.xhtml
  5. tmpdir/notavail.stamp
tmpdir/lectures/индекс/страница.xhtml
  1. tmpdir/indices-simple.xml
  2. (transforms/lectures-индекс.xsl)
  3. (transforms/lectures-by-sth-clean.xsl)
  4. tmpdir/lectures-индекс.xml
  5. (content/index-index.xsl, content/index-item.xsl)
  6. tmpdir/lectures/индекс/страница.xhtml
tmpdir/bible/%.xhtml (всички XHTML файлове на Библията)
  1. bible/bible.xhtml
  2. (content/bible-link.xsl)
  3. tmpdir/bible.xhtml
  4. (content/bible.xsl)
  5. tmpdir/bible/%.xhtml

Отделни файлове

tmpdir/index.gen.xhtml
  1. tmpdir/books-ext.xml
  2. content/index.xsl
  3. tmpdir/index.gen.xhtml
tmpdir/books/index.gen.xhtml
  1. tmpdir/books-ext.xml
  2. content/index-books.xsl
  3. tmpdir/books/index.gen.xhtml
tmpdir/books/lectures.gen.xhtml
  1. tmpdir/books-ext.xml
  2. (content/books-lectures.xsl)
  3. tmpdir/books/lectures.gen.xhtml
tmpdir/books/%.gen.xhtml (за всеки клас от книги)
  1. tmpdir/books-ext.xml
  2. (content/books-lectures-class.xsl)
  3. tmpdir/books/%.gen.xhtml
tmpdir/pending.gen.xhtml
  1. pending.xml
  2. content/pending.xsl
  3. tmpdir/pending.gen.xhtml
tmpdir/bibliography.gen.xhtml
  1. tmpdir/books-ext.xml
  2. content/bibliography.xsl
  3. tmpdir/bibliography.gen.xhtml
tmpdir/{index,lectures/index,pending,books/index,bibliography}.xhtml
  1. tmpdir/%.gen.xhtml
  2. (content/link-other.xsl)
  3. tmpdir/%.xhtml
tmpdir/{published-books,techinfo,about,todo}.xhtml
  1. content/%.xhtml
  2. (content/link-other.xsl)
  3. tmpdir/%.xhtml

Всеобхватни правила

htmldir/**/*.html
  1. tmpdir/**/*.xhtml
  2. (content/document.xsl)
  3. htmldir/**/*.html
stampdir/{document.css,favicon.ico,robots.txt}
  1. content/%
  2. (копиране)
  3. stampdir/%
tmpdir/redirected.xhtml
  1. redirects.xml
  2. (content/redirects.xsl)
  3. tmpdir/redirects.stamp