"QSP: Типограф" - Модуль форматирования текста

Версия: 1.6

Автор: Olegus t.Gl.
e-mail: olegus.tgl@gmail.com
jabber: olegus@jabber.ru
icq: 145540276

Тема на форуме iFiction.Ru: ссылка
Тема на форуме QSP: ссылка
Актуальная документация к последней версии: ссылка

О модуле

Платформа QSP позволяет использовать HTML в описании локаций, дополнительном описании и т.п. (USEHTML=1), что добавляет возможностей по части форматирования текста. Это здорово, однако, html-теги изрядно утяжеляют текст, делая его исходник не только сложным для прочтения, но и неудобным для редактирования.

Данный модуль решает некоторые проблемы с помощью сокращённых форм записи тегов. Например, чтобы пометить часть текста как параграф (html-тег параграфа <p>) нужно в начале параграфа поставить "п.", для заголовка — "з1.", чтобы прижать текст к правому краю экрана — ">.". Чтобы сделать текст жирным, нужно в начале и в конце нужного участка текста поставить символы "**", а чтобы сделать наклонным — "//".

Также модуль делает ещё несколько полезных вещей: заменяет знак дефиса в нужных местах на длинное тире (—), несколько точек — на символ многоточия (…), а также расставляет по тексту "правильные" кавычки и заменяет некоторые знаки и дроби.

"Заимствования" в модуле

Функционал данного модуля является по сути компиляцией идей и наработок, почерпнутых из следующих источников:

Модуль "Textile", входящий в CMS "Textpattern", реализующий краткую запись html-тегов. Взята общая идея записи тегов.
Модуль "WP Typograph Full" который в свою очередь базируется на идеях и исходных кодах кучи скриптов (по ссылке всё это есть). Взято по части замены некоторых символов.
Модуль "Кавычкер" Дмитрия Смирнова (spectator.ru). Само собой, реализация модуля расстановки кавычек взята оттуда полностью.

Варианты модуля

Начиная с версии 1.5 модуль поставляется только с русскоязычными вариантами команд и тегов.

Входящие в пакет файлы

otg_lib_typograph.qsp	Сам модуль.
example_typograph.qsp	Пример работы с модулем.
otg_lib_typograph_help.html	Документация по работе с модулем (вы как раз ее читаете)

Подключение модуля

Первым делом необходимо подключить к своему проекту сам модуль. Для этого файл модуля нужно скопировать в тот же каталог, в котором находится основной проект, после чего в начало кода проекта добавить команду "ADDQST" (для QSP версии 5.7.0):

Подключение модуля:

ADDQST 'otg_lib_typograph.qsp' & GS 'Типограф.Инициализация'

Практически все локации модуля начинаются с префикса "Типограф." или "otg_" (см. перечень команд), а переменные — с префикса "otg_", поэтому пересечения с данными основного проекта быть не должно.

Использование модуля

Основной функционал модуля заключается в преобразовании кратких тегов разметки текста в стандартные html-теги.

Теги заголовков

з1. … з6. Запись "з1. Заголовок" будет заменена на "<h1>Заголовок</h1>".

В заголовок включается текст от тега "з(1-6)." и до конца строки.

Блочные теги

п.	Запись "`п. Текст`" будет заменена на "`<p align=justify>Текст</p>`".
кс.	Запись "`кс. Текст`" будет заменена на "`<p align=justify>     Текст</p>`".
цт.	Запись "`цт. Текст цитаты`" будет заменена на "`<blockquote><p align=justify>Текст цитаты</p></blockquote>`".
<.	Запись "`<. Текст`" будет заменена на "`<div align=left>Текст</div>`".
>.	Запись "`>. Текст`" будет заменена на "`<div align=right>Текст</div>`".
><.	Запись "`><. Текст`" будет заменена на "`<div align=center>Текст</div>`".
о:NNN.	Формирует блок текста с заданным (в NNN) отступом. Отступ может задаваться как просто числом (пикселы), так и процентом. Блок преобразуется в таблицу, состоящую из двух колонок - ширина левой колонки соответствует указанному отступу. Таблица обрамляется в "<div>" - иначе html-движок QSP косячит с предыдущим абзацем. Например: "`о:25%. Текст с отступом`".

Блочные теги обязательно желательно заканчивать двойным переводом строки, хотя если следующая строка начинается с блочного же тега, модуль будет обрабатывать эти участки отдельно. Одинарные переводы входят в блок.

Например:

п. Первый абзац.
Выглядит вроде как вполне компактно.

цт. Заумная цитата.

>. Автор цитаты

п. Второй абзац.

о:33%. Текст с отступом в треть экрана.

Так тоже, в принципе, можно:

><. Текст по центру
п. Первый абзац.
Выглядит вроде как вполне компактно.
п. Второй абзац.

ПРИМЕЧАНИЕ: У всех описанных выше тегов после точки должен идти хотя бы один пробел!

Строчные теги

$$	Запись "`$$FA950E:Текст$$`" будет заменена на "`<font color=#FA950E>Текст</p>`". Можно использовать трёхсимвольное обозначение цвета.
**	Запись "`Текст`" будет заменена на "`<b>Текст</b>`".
//	Запись "`//Текст//`" будет заменена на "`<i>Текст</i>`".
__	Запись "`__Текст__`" будет заменена на "`<u>Текст</u>`".
^^	Запись "`^^Текст^^`" будет заменена на "`<sup>Текст</sup>`".
~~	Запись "`~~Текст~~`" будет заменена на "`<sub>Текст</sub>`".
++	Запись "`++Текст++`" будет заменена на "`<font size=+1>Текст</font>`".
--	Запись "`--Текст--`" будет заменена на "`<small>Текст</small>`".
##	Запись "`##Текст##`" будет заменена на "`<font face=Courier>Текст</font>`".

Прочее

==…==	Запись "`==Текст==`" будет исключена из обработки модулем и войдёт в конечный текст как "`Текст`".
/* … */	Запись "`/Текст/`" будет просто вырезана из текста, как-будто её там и не было.
<html> &hellip </html>	Запись "`<html>Текст</html>`" будет обрабатываться как обычный html-текст.
<pre> &hellip </pre>	Запись "`<pre>Текст</pre>`" будет исключена из обработки модулем и войдёт в конечный текст как "`<pre>Текст</pre>`".
~	Данный символ в конце строки (даже если это единственный символ в строке) будет заменён на "`<br/>`".
----	Строка, состоящая из четырёх дефисов, заменяется на "`<hr/>`".

Кроме того

Помимо замен символов модуль вносит в текст кое-какие правки:

Заменяет кавычки " на «ёлочки» и „лапки“
Заменяет последовательность точек (от трёх до пяти) на символ многоточия: …
букву "x" между двумя цифрами заменяет на знак умножения: ×
заменяет дроби 1/2, 1/4, 3/4 на соответствующие символы: ½, ¼, ¾
заменяет последовательность символов "+-" на соответствующий знак: ±
заменяет знак дефиса между двумя цифрами на знак минуса: −

Перечень команд

Типограф.Инициализация	Инициализирует работу модуля: устанавливает внутренние настройки по умолчанию.
Типограф	"Типографит" передаваемый текст.
Типограф.Отступ	Устанавливает, как должен выглядеть отступ, использующийся в теге "кс.".
ПустаяСтрока	Проверяет, можно ли считать строку пустой (т.е. в ней нет ни одного "значимого" символа).
html	Заменяет специальные символы в тексте, на их html-обозначения.
m2s	Убирает переводы строк из текста
m2ts	Убирает переводы строк из текста, обрезая пробелы и символы табуляции в начале и в конце каждой строки

Описание команд

Типограф.Инициализация

Инициализирует работу модуля: устанавливает внутренние настройки по умолчанию. Использовать лучше всего в связке с командой загрузки модуля.

Синтаксис:

GS 'Типограф.Инициализация'

Пример:

ADDQST 'otg_lib_typograph.qsp' & GS 'Типограф.Инициализация'

Типограф

"Типографит" передаваемый текст.

Синтаксис:

func('Типограф', <Текст>, <html>)

Параметры:

Текст

Обязательный параметр. "Сырой" текст, в котором используются краткие записи html-тегов.

html

Необязательный параметр. Если не указать или указать 0, то текст будет рассматриваться как обычный текст, без html-тегов, т.е. символы "<", ">", "&" будут экранированы. Для вставки в такой текст html-блока, нужно использовать запись <html> … </html>. Однако если передаваемый в функцию текст содержит html-код (без тегов <html>), например, сложное форматирование, таблицы и т.п. — то имеет смысл устанавливать этот параметр, отличным от нуля.

Пример передачи текста именно как текста:

*NL func('Типограф', '
  п. Первый абзац.
  Выглядит вроде как вполне компактно.

  цт. Заумная цитата о том, что 2 < 5.

  <html>
    Отобразим какой-нибудь особенный html-тег, например:
    <hr with=30%>
  </html>

  >. Автор цитаты

  п. Второй абзац.
')

Пример передачи текста как html-текста:

*NL func('Типограф', '
  п. Первый абзац.
  Выглядит вроде как вполне компактно.

  <table>
    <tr>
      <td>Фрукт</td>
      <td>Цвет</td>
    </tr>
    <tr>
      <td>Апельсин</td>
      <td>Оранжевый</td>
    </tr>
    <tr>
      <td>Лимон</td>
      <td>Жёлтый</td>
    </tr>
  </html>

  п. Второй абзац.
',1)

Типограф.Отступ

Устанавливает, как должен выглядеть отступ, использующийся в теге "кс.". По умолчанию отступ выглядит как пять неразрывных пробелов.

Синтаксис:

GS 'Типограф.Отступ', <Текст>

Параметры:

Текст

Обязательный параметр. Текст, содержимое которого будет использоваться в качестве отступа.

Пример:

GS 'Типограф.Отступ', '&nbsp;&nbsp;&nbsp;'

ПустаяСтрока

Проверяет, можно ли считать строку пустой (т.е. в ней нет ни одного "значимого" символа). Символы пробела, табуляции, перевода строки и возврата каретки к "значимым" символам не относятся.

Синтаксис:

func('ПустаяСтрока', <Текст>)

Параметры:

Текст

Обязательный параметр. Проверяемый текст.

Пример:

if func('ПустаяСтрока', $text):
  *NL 'В тексте что-то есть!'
end

html

Заменяет специальные символы в тексте, на их html-обозначения:
< заменяется на <
> заменяется на >
& заменяется на &

Синтаксис:

func('html', <Текст>)

Параметры:

Текст

Обязательный параметр. Текст, в котором нужно заменить специальные символы на их html-обозначения.

Пример:

*NL func('html', '<blockquote>Цитата</blockquote>')

m2s

Убирает переводы строк из текста.

Синтаксис:

func('m2s', <Текст>)

Параметры:

Текст

Обязательный параметр. Текст, из которого нужно убрать переводы строк.

Пример:

*NL func('html', '
Вы стоите посреди прекрасного мира.
    Вокруг вас слоняются мальчики-людоеды и растут кусты-убийцы.
')

Данная функция возвратит "склеенный" текст: "Вы стоите посреди прекрасного мира. Вокруг вас слоняются мальчики-людоеды и растут кусты-убийцы."

m2ts

Убирает переводы строк из текста, обрезая пробелы и символы табуляции в начале и в конце каждой строки.

Синтаксис:

func('m2ts', <Текст>)

Параметры:

Текст

Обязательный параметр. Текст, из которого нужно убрать переводы строк и "лишние" пробелы.

Пример:

*NL func('html', '
Вы стоите посреди прекрасного мира.
    Вокруг вас слоняются мальчики-людоеды и растут кусты-убийцы.
')

Данная функция возвратит "склеенный" текст: "Вы стоите посреди прекрасного мира.Вокруг вас слоняются мальчики-людоеды и растут кусты-убийцы."

Перечень изменений

Версия 1.6:

Изменён порядок вызова обработчиков текста, в результате чего исчезли некоторые глюки.

Версия 1.5:

Прекращена поддержка англоязычных команд и тегов.
Добавлена функция "ПустаяСтрока".
Добавлен тег "кс.".
Добавлена команда "Типограф.Отступ".
Добавлена команда "Типограф.Инициализация".
Улучшена обработка блочных тегов.

Версия 1.4:

Исправлен баг с блочными тегами внутри строки.

Версия 1.3:

Исправлены последствия одной автозамены.

Версия 1.2:

Исправлен недочёт в реализации тега $$ - теперь цветом можно выделять многострочный блок.
Убрана замена символа ' на html-код "'", потому как это портит ссылки в QSP.
Немного почищен код.

Версия 1.1:

У функции "Типограф" появился второй параметр. Если параметр не указан (или указан 0), то все символы "<", ">", "&" в тексте экранируются, т.е. выводятся именно как символы, а не части записи html-тегов.
Для тегов "h(1-6).", "p." и "bq." добавлены русскоязычные синонимы: "з(1-6).", "п.", "цт." соответственно.
Сочетание "----" (на отдельной строке) заменяется на тег "<hr/>".
Блоки "<pre>…</pre>" исключаются из обработки.
Блоки "/*…*/" полностью вырезаются из исходного текста (комментарии!).
Добавлен тег "о:NNN." (англоязычный вариант: "i:NNN."), где NNN - отступ в пикселах ("о:25." - 25 пикселов) или процентах ("о:25%." - 25%). Блок преобразуется в таблицу, состоящую из двух колонок - ширина левой колонки соответствует указанному отступу. Таблица обрамляется в "<div>" - иначе html-движок QSP косячит с предыдущим абзацем.
Добавлена автозамена некоторых символов: дробей, знака умножения, многоточия и т.п.