Переработка справки

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

Вопрос как всегда лишь в одном, кто займется переделкой? Необходимо, чтобы этот человек очень хорошо разбирался в QSP.

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

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

и так - qsp 564 help:

о программе (не совсем понятно о какой из программ - плеере, редакторе или эээ другом редакторе? может стоит назвать “о программах” и добавить подразделы по каждой из программ?)

лицензионное соглашение

лицензия на русском
лицензия на английском

системные требования
благодарности

принцип работы (может назвать сей загадочный пункт всётаки “описание интерфейса” потому что принцип работы это скорее разбор кода программы…)

работа с редактором игр (интерфейс редактора QGEN)
работа с утилитой TXT2GAM (добавить пункт про графический интерфейс)
принцип работы QSP (интерфейс игрового плеера QSP)

(поменять пункты местами: сначала плеер, потом куген, потом тхт2жам, добавить картинки)

операторы и функции

обозначения
выражения

использование массивов

операторы
[list]базовые операторы языка QSP
работа с действиями
работа с инвентарём
работа с переменными/массивами
условные выражения и переходы
работа с файлами
настройка интерфейса
мультимедийные возможности: звук и музыка (сделать подраздел и запихнуть туда два пункта)
мультимедийные возможности: графика
многострочные “if/act”

функции

базовые функции языка QSP
работа с действиями
работа с инвентарём
работа с массивами
работа со строками
функции, использующие регулярные выражения

системные переменные

базовые системные переменные
переменные, задающие обработчики событий
переменные настройки интерфейса

создание меню для предметов
использование тегов хтмл при разработке игр
использование регулярных выражений

введение в регулярные выражения

всяко разно

подсказки/советы
чаво
словарь терминов

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

появилась такая мысль:
сделать один главный пункт, назвать его типа “Quest Soft Pack” и уже внутри него четыре раздела:

проигрыватель QSPleer
редактор Qgen
конвертер TXT2GAM
дополнительная информация (при необходимости)

а уже в каждом из разделов своя справка.

Как и собирался, пару недель назад, наконец занялся переделкой справки. idleberry видимо тоже завис - если сделает что то хорошее, посмотрим потом.
Выкладываю черновой вариант. Многое из того что планировал оказалось не нужным.
Скажите как получилось, но главное что надо исправить:
ваши варианты текста,
небольшие дополнительные примеры (комментарии приветствуются),
опечатки в словах,
описание каких новых функций надо добавить - можете написать тут или в теме “доработка справки”, но желательно со ссылками на описание или просто пояснениями.
Тему “доработка справки” почти не трогал и не всё там понятно.
Из обновлений 5.7.0 написал про elseif и loc, а дальше не понял - объясните пожалуйста.

Файл:Help

Baz,
по magnet-ссылке попробовал, не качает. Выкладывай лучше средствами форума, ссылка “Вложить файл” прямо под полем редактирования, либо на http://rghost.ru/ .

Help
Спасибо за подсказку про возможности форума - не заметил. А с торрента должно качать, когда есть хоть один раздающий - в общем хорошая штука, когда работает (того файла теперь уже нет).

Посмотрел.

Напомню, о чём я писал в самом начале, в первом моём ответе в этой теме:

Необходимо, чтобы этот человек очень хорошо разбирался в QSP.

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

Навскидку несколько примеров.

Если в начале имени поставить знак “$”, то переменная будет считаться как текст, если #, то как число.

Что это за отсебятина? Никакого специального символа “#” для переменных не существует, это лишь справочное обозначение, придуманное Байтом специально для примеров в справке, чтобы отличать числовое выражение от символьного. Более того, в переработанной версии справки лучше не писать “#” вообще - как раз потому, что путаницы от неё больше, чем пользы.

Очень часто она используется для проверки некоего события в прошлом, которое влияет на сюжет в данный момент.
Например в сюжете есть закрытая дверь. Открыть её можно только ключём находящимся на локации “Лес_поляна_01”.
В этой локации мы создаём действие “Ключ” с кодом
key=1
При попадании игрока на эту локацию он может заметить ключ и “поднять” его нажав на действие “Ключ”.

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

На самом деле в реальной игре кроме сообщения об открытии двери надо делать продолжение, например простой переход на другую локацию с помощью goto.

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

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

“Учебник по AeroQSP” требует тщательной доработки, прежде чем быть включенным в справку. В том числе там грубая ошибка с переменной “LOC”, про которую я писал в комментариях к статье. Ну а без внятного форматирования эта гора текста вызовет у автора только ужас.

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

Что же делать?

Если ты готов к серьёзной работе, можно сделать так. Я заведу репозиторий на GitHub, дам доступ желающим дорабатывать справку. Нужно будет определить куратора - знатока QSP, который будет оценивать коммиты и вносить либо не вносить эти изменения, или возвращать на доработку. Вы вместе с куратором зальёте туда справку в её нынешнем виде, причём в исходниках, и для начала дополните её примерами, исправите ошибки и опишете то, что ещё не описано. Только после этого, когда обновлённая справка будет готова и мы с одобрения Байта опубликуем её вместо нынешней, можно будет определить структуру новой версии справки и начать работу по созданию новой версии, уже сработавшейся командой.

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

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

Моей целью было переработка справки - перетасовать и удобнее представить уже существующую информацию. Для этого не надо очень хорошо знать QSP (который к тому же, по отдельности, весьма прост), так что на мой взгляд получилось не так уж и плохо. Полностью самостоятельно переделывать справку я и не собирался - я хотел улучшить её как могу, а затем по отзывам специалистов исправить и дополнить что понадобится. Знак решётки можно и убрать - не велика потеря.

Насчёт существующего учебника: всё же он излишне большой и на мой взгляд сокращать его необходимо. И не надо заставлять людей выполнять эти простейшие упражнения. И не надо делать в одном учебнике несколько проектов в каждом из которых надо создавать локации и прописывать пути - это делает его ещё скучнее. Это учебник для начинающих (возможно вабще не знакомых с программированием), поэтому там нужны простые примеры, основанные только на уже известном, а не из реальных игр с кучей непонятных новых команд. Этот учебник часть справки и может ссылаться на другие разделы, а если раздел написан понятно, то незачем его переписывать дважды.
Исходя из этого я и сделал такую сокращённую версию - и другие разделы тоже старался править что бы они стали более понятными для начинающих.

Кстати, раздел выражений я попытаюсь ещё разделить.

Учебник по Aero действительно выглядит плохо и требует переработки (слишком большой и сложный что бы я смог это сделать), но не включать его нельзя, т.к. информация по аэро необходима и пусть будет в плохом виде, чем не будет никакой.

Насчёт примеров - если внимательно изучать справку, то примеров к существующим статьям добавлять почти и не нужно, а если добавлять то лучше с комментариями. Те сложные примеры что есть на сайте в виде отдельных файлов - видимо внедрить в саму справку не удастся, поэтому я подумал что их можно сложить в один архив, снабдить поясняющим файлом и приложить к справке (что бы они скачивались вместе в одном архиве).

Репозиторий (что бы это нибыло) - отличная идея, но стрёмная немного, возникает много вопросов: надо дополнительно регистрироваться, сохранится ли подобное удобное форматирование этой программы, как чисто технически будет выглядеть процесс редактирования и компиляции, будет ли куратор открыт для свежих идей (можно ли будет убедить его что разделы операций и функций стоило соединять вместе)?

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

Мой “отзыв специалиста” был для тебя недостаточно убедителен. Что ж, жди других отзывов.

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

Мне, как начинающему в QSP, старый учебник показался излишним

А теперь главный вопрос: имел ли ты опыт в программировании хоть чего-либо, до знакомства с учебником? Имел ли представление о том, что такое переменная и условие - не конкретно в QSP, а вообще как понятие?

Конечно я с этим немного знаком, но всё же я старался сокращать так, что бы было понятно именно новичкам, при внимательном прочтении. Узнавал ли кто-нибудь сколько людей и с каким уровнем приходит, что они думают о текущем учебнике?
Предположим что всё верно и объём учебника и требования к выполнению даже простейших заданий справедливы. Но пожалуй больше всего мне не нравится то, что там создаётся несколько разных проектов - не лучше ли во всём учебнике создавать единый большой проект - это сделает его более понятным и заодно немного сократит.
Про рельные примеры: я видел несколько книг с подобным и лично мне это было неудобно, когда для описания одной простейшей операции, в самом начале книги, приводится большой кусок реального кода с огромным количеством сложных конструкций и ещё не известных операторов.
И вопрос попроще: вместо того что бы писать болшую отдельную статью про IF я сделал введение и ссылку на полный раздел справочника - этот раздел простой, понятный и после изучения азов уже должно быть не трудно в нём разобраться. Разве не разберутся?
Относительно учебника всё же хочется услышать другие мнения - в идеале, дать паре новичков оба и спросить что они думают (результат предсказуем, но надеюсь не так ужасен, как вы говорите).

Конечно я с этим немного знаком

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

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

Ясно, что учебник отдельная тема. Если есть аргументы, то может в личке лучше общаться? Если нет, то создам тему на форуме с моими вопросами.

Оставшееся постараюсь доделать на выходных. Остальные вопросы потерпят до этого времени.