3 posts tagged with "документация"

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

Это раздел, в котором собраны все операторы, функции, системные переменные, а так же спецсимволы и синтаксемы языка QSP.

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

Чтобы комфотно работать в Обсидиане и не терять функциональность ссылок в Докузаурус, необходимо следовать некоторым правилам:

• Имена файлов должны начинаться с буквы, но ни в коем случае не с цифры.
  Потому что:

  Докузаурус опускает числа в начале имён файлов. Из-за этого ссылки валидные в Обсидиане не будут работать в Докузаурусе. (Соответственно порядок размещения статей должен определяться через поле sidebar_position в yml-заголовке документа).

• Необходимо смириться с тем, что ссылки на index.md раздела не будут работать в докузаурусе, либо, если их "обрезать" для докузауруса, не будут работать в обсидиане. Лучше избегать создания разделов index.md для комфортной работы и там и там.
• Ссылки на файлы статей должны быть относительными (чтобы работать и там и там), и включать так же расширение файлов (.md).
  ../language/qsp-keywords/qsp-keywords-functions.md
  Потому что:

  Докузаурус опускает расширение .md в ссылках и таким образом в процессе работы ссылки поддерживаются и в обсидиане и в докузаурусе. После сборки ссылки во всех статьях приобретают вид валидный для докузауруса, но невалидный для Обсидиана.
  https://dev.qsp.org/docs/language/qsp-keywords/qsp-keyword-operators

• Необходимо смириться с тем, что обсидиан не поддерживает те же якоря заголовков, что и докузаурус, из-за чего сослаться на заголовок в обсидиане так же как в докузаурусе невозможно. Это не мешает обсидиану поддерживать такие ссылки при изменении местоположения статей и разделов.

Добавил в документацию Docusaurus подсветку синтаксиса для кода QSP. Она весьма проста, и умеет подсвечивать синтаксис на самом примитивном уровне. Тем не менее работает уже довольно сносно, не считая некоторых артефактов.

Например:

if ваза_на_столе=1:
  ! если переменная-маркер ваза_на_столе равна 1

  ! создаём действие
  act "Взять вазу со стола":
    ! в действии изменяем значение переменной-маркера
    ваза_на_столе=0
    addobj "Ваза"
    goto $curloc
  end
end

Другой пример:

# start
result = 123  & ! записываем число в переменную result
N=24
*pl func('square')  & ! выведет на экран 576
*pl result  & ! выведет на экран 123
- start -

vase_on_desk = 0

# square
result = N * N
- square -

И ещё пример:

# em.summ
local $_, $res
if $args[0]='': exit  & !@ если не указано имя массива. Защита от дурака
if $args[1]='':
  !@ если аргумент не указан, в качестве разделителя используется пробел
  $args[1]=' '
elseif $args[1]='/se':
  !@ если аргументом указан ключ, разделитель не используется
  $args[1]=''
end
!@ если указан текстовый массив, помечаем в переменной-маркере
if instr($args[0],'$')=1: $_='$'
loop local i,size=0,arrsize($args[0]) while i<size step i+=1:
  if $_='$':
    !@ для текстовых массивов раюотает конкатенация
    $res+=$dyneval("$result=<<$args[0]>>[<<i>>]")+$args[1]
  else
    !@ для числовых суммирование
    res+=dyneval("result=<<$args[0]>>[<<i>>]")
  end
end
!@ возвращение результата
if $_='$':
  $result=$res
else
  result=res
end
--- em.summ ---------------------------------

Установка подсветки в ваш Docusaurus весьма проста:

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

   npm run swizzle @docusaurus/theme-classic prism-include-languages
   

   При этом будет создан файл "src/theme/prism-include-languages.ts" (или .js).

2. В папке "src/theme" создайте папку qsp-syntax и скопируйте в неё файл "prism-qsp.js", например, отсюда.

3. В файле "src/theme/prism-include-languages.ts" отредактируйте функцию prismIncludeLanguages:

   export default function prismIncludeLanguages(PrismObject: typeof PrismNamespace,): void {
     // ...
     additionalLanguages.forEach((lang) => {
       // ...
       require(`prismjs/components/prism-${lang}`);
     });
     require('./qsp-syntax/prism-qsp.js');
     // ...
   }
   

4. Далее вы можете создать собственный файл стилей, положить его рядом с common.css и прописать путь в docusaurus.config.ts:

   presets: [
   [
     'classic',
     {
       docs: {
         // ...
       },
       blog: {
         // ...
       },
       theme: {
         customCss: [
           './src/css/custom.css',
           './src/css/qsp-syntax.css'
         ]
       },
       // ...
   

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

После сохранения и перезапуска сервера, или при сборке проекта, подсветка QSP-кода подхватится.

Больше примеров работы подсветки можно посмотреть в онлайн-версии справочника по самым часто задаваемым вопросам о QSP, на котором собственно и производились опыты.

Документация как центральный орган​

Главная, как по мне, проблема Куспа, — это его децентрализованность. Это значит, что одна рука не ведает, что творит другая, а потом выясняется, что это уже давно всё сделано; а ноги вообще идут своим каким-то непонятным путем.

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

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

Когда документация выходит на сцену в разработке?​

Вот к примеру, Байт хочет ввести тип для кортежей. Он пишет в #qsp_platform_dev свои планы, и начинается обсуждение в духе: "Какой символ использовать?", "Какие проблемы решает новый тип?" и т.д. На все вопросы рано или поздно находятся ответы, обсуждение к чему-то приходит, но всё это сейчас находится в чатике в виде разрозненных сообщений.

Обобщение напрашивается само по себе, но вот куда его писать? Прямо в документацию? Пока рано, потому что оно сырое и его нужно уточнять. Поэтому в документации у нас существует блог (да, в документации есть документация и блог, пусть это вас не смущает), куда можно писать свои мюсли в произвольном виде (вот, к примеру, как этот пост).

Я вот, к примеру, пишу пост-обобщение про тип кортежей, затем показываю его участникам в чате. Всё это дело правится, одобряется, пересматривается и в конце концов пост отправляется в документацию (скорее всего, материал пойдет в раздел языка QSP, где ему самое место).

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

Каким языком должна писаться документация?​

Писать ли документацию в более техническом стиле или, наоборот, писать в стиле научно-популярном — вопрос тяжелый. Чтобы попытаться на него ответить, нужно определить аудиторию.

У нас имеются:

• разработчики самого Куспа
• разработчики игр на Куспе

С одной стороны, понятно, что документацию нужно писать непосредственно для самих разработчиков, но с другой стороны, разработчики игр порой и сами не понимают, что им сейчас доступно, и пользуются чем-то устаревшим и ограниченным.

Порой диву даешься, как им удается выжимать из такого скудного набора инструментом такие большие проекты! Да и обидно становится, что разрабатываешь всякий инструментарий, а никто не пользуется. Поэтому к разработчикам игр нужно как-то доносить всё это современно ноу-хау.

А бывает так, что и сами разработчики игр сами создают инструменты. Я почему-то уверен, что ребята из GLife были простыми разработчиками игр на QSP, а потом как-то умудрились додуматься до контроля версий GIT, что надо всю эту махину растаскивать по отдельным исходникам, даже расширение придумали для них — .qsrc. Я вот, к примеру, не знал об этом, и вляпал свое .qsps для расширения VS Code. В итоге у нас идет два разрозненных стандарта расширений для исходников, и какой из них "правильнее" — кто его знает. Скорее всего, придется поддерживать два типа.

Документация должна отсекать такие случаи и приводить к общему знаменателю. А чтобы в документации разобраться, нужно писать ее как можно более понятнее. А что такое "более понятнее" — фиг его знает!

Возможно, научпоп надо отдать на откуп евангелистам (Aleks Versus, к примеру, занимается этим на своем канале) и не сушить себе голову, а может, надо немного уменьшить градус техничности. Истина где-то рядом.

Структура документации​

Сейчас написано мало и толком непонятно, как всё это структурировать.

Предлагаю сделать структуру пока что такой:

• QSP Foundation — о том, что это всё такое, зачем оно надо и т.д. Возможно, стоит вклинить туда этот пост
• Совместная разработка — статья о том, как заполнять документацию, чтобы не наступить друг другу на ногу. Скорее всего, название неудачное и надо его сменить
• Общий взгляд — сейчас это называется "Всё вместе". Здесь нужно показать, как все сущности стыкуются между собой
• язык QSP — спецификация языка, т.е. то, с чего по-идеи должен начинаться QSP и от чего наследуются остальные сущности
  • синтаксис — по-идеи, тут надо изложить полное синтаксическое дерево от значений до локаций в каком-то всем понятном формате. Я поглядываю в сторону EBNF с визуализацией, но это надо обсуждать
  • семантика — предопределенные переменные, процедуры, функции и т.п., что они означают и как работают
• Парсеры — раздел с парсерами
• Интерпретаторы (движки? Т.е. прослойка между парсерами и плеерами)
• Компиляторы (штуки, который преобразуют код QSP в нечто другое) — пока что мне известен только компилятор qsp-to-js Garret'а и qsp-to-twine ребят из GLife, но, возможно, их больше
• Плееры
• Разработка
  • Редакторы — краткое описание QGen, к примеру
  • Расширения для редакторов — краткое описание JAD и Qsp.FSharp.VsCode
  • Анализаторы
    • вот тот анализатор на C#
    • какой-то неизвестный анализатор на OCaml
• Персоналии — раздел, в котором перечислены разработчики экосистемы, кто чем занимается и к кому в случае чего обращаться. Друзей надо знать в лицо! Что-то вроде персоналии в IFWiki, но с разработчиками