| Автор | Сообщение |
|---|
JSO x
= 2nd Lieutenant =
 | | 1452 |
Doom Rate: 2.33
Posts quality: +800 |
 Отправлено: 08.02.26 13:53:46 | |
|
Доброго времени суток!
ZScript — не самый элементарный язык, и большинство хороших руководств, документаций и статей по нему есть только на английском языке. Существующие русскоязычные ресурсы либо покрывают какую-то небольшую часть, либо, к сожалению, остались доступны только в архивах.
Устойчивый спрос на ZScript в русскоязычной среде есть, и поэтому такое положение дел — с минимумом информации — необходимо исправлять. Итак, объявляю анонс первой публичной версии наиболее полного руководства по ZScript на русском языке!
Сайт руководства:
https://zscript-rus-manual.readthedocs.io/latest/
Там же "Быстрый старт" и страница оглавления.
Репозиторий проекта:
https://github.com/LLDM-Doom-Modding/zscript_rus_manual
Что ещё важно, данное руководство никуда не денется, даже если куда-то денутся все авторы — работу на данный момент обеспечивают два известных хостинга.
Внимание! Проект на данный момент находится в глубокой разработке, поэтому часть статей или разделов пока что отсутствует, в остальных же могут попадаться ошибки.
Просьба относиться с пониманием и по возможности о них сообщать или сразу исправлять. Конструктивная критика приветствуется, а отзывы и помощь дают огромный приток мотивации.
В руководство включается:
- Непосредственно раздел руководства — глава "Первый мод";
- Документация с дружелюбными примерами использования (главы от 3 до 6), а также полноценные примеры готового кода в отдельном разделе;
- Ссылки на ресурсы, где могут помочь разобраться с ZScript;
- Советы и решения, полученные из опыта (встречаются повсеместно и иногда в отдельных статьях);
- Как на самом деле работает движок — разбор внутренней работы движков семейства *ZDoom и языка ZScript;
- Списки частых ошибок, списки действительно неординарных багов, список ошибок компилятора — и, конечно, как их всех отслеживать и решать.
На данный момент написаны не все статьи — к примеру, глава 2 "Первый мод" включает в себя 7-8 статей, но готовы из них пока только 3.5. Прогресс можно отслеживать в репозитории проекта и в канале "#zscript-rus-manual-commits" Discord-сервера Russian Doom Discord Community. Пока что основная ветка разработки также находится на RDDC, в форум-канале "#Русскоязычный мануал по ZScript. Канал разработки". Новости в первую очередь будут публиковаться там и в этой теме на iddqd.ru.
Связаться с авторами можно:
- На большинстве серверов общей направленности в списке всех отечественных Doom-Discord-серверов;
- Здесь, в этой теме или в личных сообщениях iddqd.ru;
- В issues на GitHub;
- Где-нибудь ещё, где будет удобно общаться и где переписка не потеряется.
* * *
Ищем авторов и редакторов!
За всё время, считая только текстовые файлы статей размером более 1 Кб, было написано 396 Кб текста. За последние три ударные недели перед выпуском первой версии добавлено 112 Кб, или 957 строк/абзацев (подсчёт ведётся по символу новой строки), с учётом заменённых абзацев 1467. Если эти три недели смотреть по всем попарным изменения между соседними коммитами, заменено 1049 строк/абзацев, добавлено — 4328.
Конечно, это уже далеко не капля в море, но проект всё ещё не завершён, и в свободном темпе будет готов хорошо если через десяток лет.
Из истории, из результатов коммерческих компаний и мира Open Source известно, что совместная работа позволяет совершать то, что невозможно одному человеку. Потому, если Вы видите неточности или видите, что можно улучшить абзац — просьба сообщать, корректура тоже отнимает много времени. Если Вы знаете ту или иную тему из мира ZScript, призываю присоединяться к разработке — лучше написать и потом совместно исправить, чем не написать вовсе! Сокращение времени основного цикла разработки до полугода (получается, в двадцать раз) — это уже огромный успех, и он вполне реалистичен.
Вся цепочка поставок настроена, при отправке изменений в репозиторий они появляются и на сайте. В минимальной комплектации достаточно будет блокнота Windows и произвольного канала связи со мной или другим разработчиком, некоторые другие варианты описаны здесь. При необходимости со своей стороны могу провести краткий экскурс в работу с git/репозиторием, про текстовый язык разметки Markdown, или даже про локальное развёртывание сервера MkDocs для необязательного предпросмотра результата.
* * *
Успехов в изучении ZScript! |
Рейтинг сообщения: +16, отметил(и): MAZter[iddqd], Mikle, VladGuardian, Dant3, Mud, camper, Endoomer, soldierDude, RaRu Des2122, Dron12261, Ear1h, EarKiller6002, Michael_63, RunnerFx, raspad, Modern Retrogamer |
|
| 3 |
8 |
1 |
 |
|
| |
Shadowman
UAC General
 | | 9329 |
Doom Rate: 2
Posts quality: +2664 |
| Отправлено: 22.03.26 21:18:49 | |
|
Отличная тема, но пользуясь случаем, дополню ее следующим вопросом.
Учитывая все ужесточающиеся блокировки, возможно предвидеть наступление часа Х, когда доступ на зарубежные ресурсы окажется полностью заблокирован, и никакой ВПН не спасет. В этой связи есть ли опыт архивирования здум-вики целиком, чтобы ей можно было пользоваться в изолированном режиме на компьютере без доступа к (зарубежному) интернету?
Может быть, пора сделать такую копию, чтобы не оказаться в случае чего вообще без ресурса?
(Понимаю, что в таком случае дум-моддинг отойдет на второй план, но все же иметь ресурс лучше, чем не иметь его вообще). |
|
|
| 1 |
8 |
2 |
|
|
| |
JSO x
= 2nd Lieutenant =
| | 1452 |
Doom Rate: 2.33
Posts quality: +800 |
| Отправлено: 25.03.26 12:54:43 | |
|
| Shadowman пишет: | | Может быть, пора сделать такую копию, чтобы не оказаться в случае чего вообще без ресурса? |
Есть статья "Downloading the ZDoom Wiki", где можно скачать ежедневно обновляемое зеркало Википедии. Движок MediaWiki, используемый на zdoom.org, со своей основной зависимостью MariaDB весит ещё 500 Мб — так что, если нет острой необходимости разворачивать свой сервер, можно с помощью проекта https://github.com/philipashlock/mediawiki-to-markdown конвертировать всё в Markdown-текст, открываемый в любом Блокноте. Или, менее изящный вариант, можно выкачать весь сайт через какой-нибудь HTTrack (но есть вероятность, что где-то на середине канал перекроют). А вот с кем договариваться об аренде сервера для некоммерческой бесплатной документации, я пока не знаю. Возможно, потребуется его у кого-нибудь арендовать.
Если говорить об этом руководстве по ZScript, то последнюю локальную версию в виде Markdown-файлов всегда можно скачать по прямой ссылке в репозитории. GitHub сейчас должен работает с любого провайдера. Надеюсь, до этого дело не дойдёт, но в крайнем случае сделаю зеркало репозитория и, если найду подходящие варианты, подниму сайт на российских серверах. Скоро как раз намеревался добавить инструкцию по конвертации всего руководства в сайт и по запуску локального сервера.
* * *
К теме проекта. Выяснил, что некоторые поисковики вроде Google слабо индексируют сайт ReadTheDocs, и это руководство в частности. Так что, оказывается, есть шанс, что его могут не найти даже при прямом запросе в поисковике... Поэтому прошу по возможности распространять ссылку на руководство там, где оно может оказаться полезным.
Сейчас время в основном получается проводить на работе, которая местами тоже связана с написанием технической документации, так что со своей стороны пока не слишком проявляю активность. Но, несомненно, проект всё так же остаётся в силе и никуда не исчезает.
P. S. Оффтоп, но заметил, что порядок имён в подсчёте рейтинга сообщения определяется по тому, кто когда зарегистрировался на сайте. Чем ближе к началу — тем старше аккаунт ꓽ) . |
|
|
| 3 |
8 |
1 |
|
|
| |
JSO x
= 2nd Lieutenant =
| | 1452 |
Doom Rate: 2.33
Posts quality: +800 |
| Отправлено: 18.06.26 20:15:05 | |
|
И вновь привет думерам!
Я намерен продолжать структуризировать известные мне области ZScript, однако с момента публикации я получил ровно одну обратную связь (а за последние семь лет — три), так что хотел бы понять, насколько это в нынешней обстановке вообще людям нужно. Пока что есть ощущение, что структуризация производится только автором для автора, и в таком случае есть смысл делать всё в полностью свободном темпе — то есть, другими словами, желательно успеть до конца жизни. Я не против, но хотелось бы услышать мнение остальных.
Ну и сканирующих ботов нейросетей текстами кормить, куда же в современности без этого. Всё-таки лично мне больше по душе создавать что-либо для людей! |
|
|
| 3 |
8 |
1 |
|
|
| |
camper
UAC Sergeant Major
 | | 740 |
Doom Rate: 1.42
Posts quality: +408 |
| Отправлено: 19.06.26 21:07:39 | |
|
| Есть планы создать документ для 6 дюймовой электронной книги в формате epub или fb2 ? Или только html? |
|
|
| |
JSO x
= 2nd Lieutenant =
| | 1452 |
Doom Rate: 2.33
Posts quality: +800 |
| Отправлено: 20.06.26 02:27:16 | |
|
Я никогда таким не занимался. Сейчас попробовал, и с третьей попытки всё же получился очень простой вариант (без половины форматирования и изображений). Однако после...
Суть в том, что напрямую из древовидной структуры MkDocs конвертеры вроде Pandoc создавать EPUB не умеют, но всё же могут принять массив Markdown-файлов в определённо разложенном виде. Так что пришлось внимательно рассмотреть справку нескольких приложений и перелопатить несколько сайтов, вспомнить Python virtual environment, разрешить проблемы зависимостей устаревших пакетов Python и возобновить когда-то маскированный демон Docker для запуска единственного оставшегося полуживого форка конвертера из MkDocs Markdown в EPUB/FB2. В итоге всё равно не получилось, падает при конвертации...
В таком случае, похоже, проще набросать свой небольшой конвертер до форматов Pandoc — конечно, не самый хороший и переносимый вариант, но, честно говоря, когда выбрал MkDocs, не ожидал, что с произвольной конвертацией из его довольно свободной структуры будут такие проблемы. Вижу ещё несколько сомнительных вариантов решения и обхода, однако пробовать реализовывать их как-то не очень хочется.
Посмотрим. "Одноразовыми" методами точно можно, так что по требованию сконвертированный файл куда-нибудь скинуть могу, но, как минимум поначалу, с большой вероятностью он может показаться полусырым. EPUB/FB2 — это чтобы в поездках читать на электронной книге, правильно? |
|
|
| 3 |
8 |
1 |
|
|
| |
camper
UAC Sergeant Major
| | 740 |
Doom Rate: 1.42
Posts quality: +408 |
| Отправлено: 22.06.26 20:03:15 | |
|
| JSO x пишет: | | но, как минимум поначалу, с большой вероятностью он может показаться полусырым |
Тогда не надо на этом заморачиваться. Лучше сделать главное - сосредоточится на тексте, пусть в html. Я учебник по декорейту в html в книжку загрузил и так читал, вполне годится. Некоторые моменты из примеров всё равно распечатать приходилось и под рукой держать.
Добавлено спустя 4 минуты 23 секунды:
Мой небольшой опыт показал, что конвертация обычно к хорошим результатам не приводит. Лучше сразу делать в специализированном редакторе:
https://sigil-ebook.com/sigil/ - для вёрстки epub
https://github.com/Sigil-Ebook/PageEdit - для набора текста для Sigil-ebook |
|
|
| |
dukenator
UAC Sergeant Major
| | 736 |
Doom Rate: 2.05
Posts quality: +123 |
| Отправлено: 24.06.26 04:07:14 | |
|
Как любитель иногда поковырять ZScript, хочу поблагодарить автора за полезное начинание) Такое чувство, что этого языка боятся даже его создатели, документации в сети кот наплакал, а на русском - и вовсе почти нет.
Желаю сил и терпения на этом тернистом пути) |
Рейтинг сообщения: +1, отметил(и): JSO x |
|
| |
JSO x
= 2nd Lieutenant =
| | 1452 |
Doom Rate: 2.33
Posts quality: +800 |
| Отправлено: 28.06.26 16:18:48 | |
|
| camper пишет: | | Лучше сделать главное - сосредоточится на тексте, пусть в html. |
Проект изначально пишется в Markdown, формат которого, в общем-то, просто текстовый файл. Пример: 2.2-Простой_декоративный_актор.md (тот же файл в сыром формате, в GitHub переключается в "Preview"/"Code" прямо над содержимым). По идее, многие приложения-читалки его тоже должны понимать, хотя бы в базовом виде.
| dukenator пишет: | | Такое чувство, что этого языка боятся даже его создатели, документации в сети кот наплакал, а на русском - и вовсе почти нет. |
Немного ссылок собрал на странице полезных ссылок. Думаю, почему бы не побыть концентратором?
Кстати, у всех ведь https://zscript-rus-manual.readthedocs.io/ и https://github.com/LLDM-Doom-Modding/zscript_rus_manual/ без средств перенаправления трафика открывается?
| dukenator пишет: | | Желаю сил и терпения на этом тернистом пути) |
Спасибо! Ещё проблема в том, что я не совсем представляю, насколько понятно читается текст, и это немного сбивает с толку. Хорошо бы забывать на два месяца, а затем возвращаться и начинать заниматься редактурой — но это не слишком хорошо ложится на продолжение описания следующих тем, постоянная правка не вдохновляет. Можно подключить LLM, хотя, честно говоря, не слишком люблю им доверять мыслевыражение. |
|
|
| 3 |
8 |
1 |
|
|
| |
Правила 
Поиск
