Новая справка по QSP.

Установил капчу на регистрацию, а то боты полезли.

Я написал про GOSUB и GS в “локации и переходы”, но автор откатил. Не согласен с позицией newsash по поводу GOSUB. С точки зрения логики обучения GS всё-таки стоит описать в одном ряду с GT и XGT. Ибо это именно что оператор перехода на другую локацию, особенность работы которого позволяет упомянуть его в разделе про “упорядочивание кода”.

HertzQ:

Ибо это именно что оператор перехода на другую локацию

Я примерно месяц обдумывал структуру справки. Готов признать, что она далека от совершенства, но в данном случае всё на своих местах.
GS (как и FUNC) - оператор, который позволяет выносить часть кода игры из основных локаций в вспомогательные, чтобы упростить их и убрать повторяющиеся куски кода. Если использовать обычную терминологию, то GS отвечает за процедуры, а FUNC - за функции. Что относится именно к упрощению и упорядочиванию кода.
При этом, после выполнения кода интерпретатор возвращается в исходную локацию, т.е. GS не является переходом.

newsash:

т.е. GS не является переходом.

GS именно что является переходом и должен стоять в одном ряду с GT и XGT.
А вы всё сводите лишь к одному из способов применения данного оператора.
Всё равно что перенести унитаз в раздел мебели, т.к. на нём можно сидеть.

Nex, рассуди.

HertzQ:

newsash:

т.е. GS не является переходом.

GS именно что является переходом и должен стоять в одном ряду с GT и XGT.
А вы всё сводите лишь к одному из способов применения данного оператора.
Всё равно что перенести унитаз в раздел мебели, т.к. на нём можно сидеть.

Полагаю, что данная классификация была принята исходя из очевидного функционала оператора, а также вполне говорящего наименования “GOSUB”. Для более точного определения своей позиции, HertzQ не мешало бы привести примеры использования GS, из которых было бы ясно, что основное предназначение этого оператора — именно в реализации ещё одного варианта перехода.

Если судить по функционалу, то XGOTO почти тот же GOSUB, только $CURLOC меняется.

HertzQ:

Если судить по функционалу, то XGOTO почти тот же GOSUB, только $CURLOC меняется.

Очень странное сравнение.
GOSUB — это вызов локации/процедуры с автоматическим возвратом в точку вызова. Это как раз то, что характеризует подпрограммы, и это же — радикальное отличие от GOTO и XGOTO, которые такого функционала не предусматривают вовсе.
Простые примеры:

GS 'Модуль'
*NL 'Отработали GOSUB'
XGT 'Модуль'
*NL 'Отработали XGOTO'

или:

GS 'Модуль'
*NL 'Отработали GOSUB'
GT 'Модуль'
*NL 'Отработали GOTO'

Ну так вот, фраз “Отработали XGOTO/GOTO” мы не увидим никогда.

HertzQ:

GS именно что является переходом и должен стоять в одном ряду с GT и XGT.
А вы всё сводите лишь к одному из способов применения данного оператора.
Всё равно что перенести унитаз в раздел мебели, т.к. на нём можно сидеть.

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

Nex (или любой другой модератор, если на форуме такие есть), предлагаю вынести обсуждение этого вопроса в отдельную тему “Является ли GOSUB переходом.”.

Olegus t.Gl., наверное, я ошибся с таким сравнением.
Честно говоря, я практически никогда не пользовался XGOTO.

GS — переход с возвратом, нет?
Кстати, я обнаружил одну вещь, которая будет аргументом против моей точки зрения.
Я считал, что при использовании GS обрабатывается $ONNEWLOC, а оказалось, что нет.

Вообще, к чему я поднял этот вопрос. Когда я стал читать новую справку и НЕ увидил описания GS рядом с GT и XGT, то первая (страшная) мысль была о том, что в новых версиях QSP оператор GS будет просто упразднён, раз описания нет. А оказалось, что оно просто переехало.

HertzQ:

Вообще, к чему я поднял этот вопрос. Когда я стал читать новую справку и НЕ увидел описания GS рядом с GT и XGT, то первая (страшная) мысль была о том, что в новых версиях QSP оператор GS будет просто упразднён, раз описания нет. А оказалось, что оно просто переехало.

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

1. Упомянуть-то “родственные” операторы никто не мешает. Более того, всё связанное по смыслу должно быть упомянуто, и не только в этой статье, а практически в каждой. Это одна из фишек любой хорошей документации: даже если с первого раза не попадаешь куда хотел, можно всегда найти по общему смыслу.

Просто написать в конце статьи
“См. также: GOSUB, FUNC”

2. Операторы GOSUB и FUNC не только “близки по смыслу” к GOTO, но и имеют прямое отношение к содержимому статьи. Статья называется “Локации и переходы”, поэтому логично упомянуть разные способы вызова локаций, а не только рассказать о переходах. Собственно они и упомянуты:

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

Это как раз про GOSUB и FUNC, только почему-то без упоминания операторов.

3.
Сам по себе раздел “Упорядочивание кода”, я думаю лучше переименовать в “Процедуры и пользовательские функции”. Так будет более понятно по смыслу.

4.
newsash перенял и развил из прежней справки способ представления “кучка операторов объединённых общей темой + описание в двух словах”. Это позволяет избавиться от специальных статей по операторам, вкрапляя определения операторов в тематические статьи. Я не уверен что это целесообразно, мне представлялось что в новой справке будет ближе к серьёзной документации, то есть статьи по операторам в виде “описание оператора + примеры”, и тематические статьи объясняющие суть вещей со ссылками на операторы. Пока не могу сказать, лучше ли такое решение, думаю время покажет.

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

Кстати да: если кто-то может предложить для операторов примеры лучше, чем сейчас - предлагайте.

мы же решили идти по пути упрощения для понимания непрограммистами

Но конкретно эта статья находится в разделе “программирование”.

К тому же “упорядочивание кода” ничего не скажет ни программисту, ни новичку. Он не поймёт что это за “упорядочивание”, пока не заглянет внутрь. А “процедуры” и “пользовательские функции” ему могут быть знакомы хотя бы по школьным курсам информатики. И это название, по прочтению статьи, у него будет впредь чётко ассоциироваться с тем чем нужно, он её легко снова отыщет.

Мы же не пишем вместо “массивы”, “представление данных в памяти” или “упорядочивание данных”?

Верно подмечено насчёт неочевидности расположения GOSUB.
Я ведь в итоге нашел описание GOSUB перебором всех статей.

К слову, всех остальных “переездов” я не заметил.
Т.е. в новой справке всё весьма удачно расположено.
Ну, кроме GOSUB ;-)

Давайте тогда подумаем как переименовать “Упорядочивание кода”.
“Процедуры и функции” мне не нравится потому, что может возникнуть путаница со встроенными в язык функциями.
Слово “пользовательские” мне не нравится, т.к. понятие пользователя у нас размыто между игроком и автором, да и слово “пользователь” для QSP лично мне слегка слух режет.

Пока лучший вариант “Пользовательские функции и подпрограммы”