2.3 Команды для получения справки

Весь текст этого руководства доступен в окне Octave по команде doc. Кроме того, документация для отдельных функций и переменных, написанных пользователем, также доступна через команду help. В этом разделе описаны команды, используемые для чтения руководства и строк документации для функций и переменных, предоставленных пользователем. См. Файлы функций, для получения дополнительной информации о том, как документировать написанные вами функции.

: help name ¶

: help --list ¶

: help . ¶

: help ¶

: help_text = help (…) ¶

Отображает текст справки для name.

Например, команда help help выводит короткое сообщение, описывающее help команду.

При единственном аргументе --list, перечисляет все операторы, ключевые слова, встроенные функции и загружаемые функции, доступные в текущем сеансе Octave.

При единственном аргументе ., перечисляет все операторы, доступные в текущем сеансе Octave.

Если вызвана без аргументов, help отображает инструкции по доступу к справке из командной строки.

Команда help может предоставить информацию о большинстве операторов, но name необходимо заключить в одинарные или двойные кавычки, чтобы предотвратить действие интерпретатора Octave на name. Например, help "+" отображает справку по оператору сложения.

См. также: doc, lookfor, which, info.

: doc function_name ¶

: doc ¶

Отображает документацию для функции function_name непосредственно из онлайн-версии печатного руководства, используя обозреватель GNU Info.

Если вызвана без аргумента, руководство отображается с начала.

Например, команда doc rand запускает обозреватель GNU Info в узле rand в онлайн-версии руководства.

После запуска обозревателя GNU Info, помощь по его использованию доступна с помощью команды C-h.

См. также: help.

: lookfor str ¶

: lookfor -all str ¶

: [fcn, help1str] = lookfor (str) ¶

: [fcn, help1str] = lookfor ("-all", str) ¶

Ищет строку str в документации всех функций в текущем пути поиска функций.

По умолчанию lookfor ищет str только в первом предложении строки справки для каждой найденной функции. Весь текст справки каждой функции можно найти, используя аргумент "-all". Все поиски регистронезависимы.

При вызове без выходных аргументов lookfor выводит список соответствующих функций в терминал. В противном случае выходной аргумент fcns содержит имена функций, а help1str — первое предложение из строки справки каждой функции.

Примечание для программирования: Возможность lookfor правильно идентифицировать первое предложение текста справки зависит от формата справки функции. Все ядровые функции Octave отформатированы корректно, но то же самое не гарантируется для внешних пакетов и функций, предоставленных пользователем. Поэтому может потребоваться использовать аргумент "-all" для поиска связанных функций, которые не являются частью Octave.

Скорость поиска значительно улучшается при наличии кэшированного файла документации. Дополнительную информацию см. в doc_cache_create.

См. также: help, doc, which, path, doc_cache_create.

Чтобы узнать о новых функциях в текущей версии Octave, используйте функцию news.

: news ¶

: news package ¶

Отображает текущий файл NEWS для Octave или установленного пакета.

Если вызывается без аргумента, отображает файл NEWS для Octave.

Если задано имя пакета package, отображает текущий файл NEWS для этого пакета.

См. также: ver, pkg.

: info () ¶

Отображает контактную информацию для сообщества GNU Octave.

: warranty () ¶

Описывает условия копирования и распространения Octave.

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

: val = info_file () ¶

: old_val = info_file (new_val) ¶

: old_val = info_file (new_val, "local") ¶

Запрос или установка внутренней переменной, определяющей имя файла справки Octave.

Значение по умолчанию — octave-home/share/info/octave.info, где octave-home — корневой каталог установки Octave. Значение по умолчанию может быть переопределено переменной среды OCTAVE_INFO_FILE, или аргументом командной строки --info-file FNAME.

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

См. также: info_program, doc, help, makeinfo_program.

: val = info_program () ¶

: old_val = info_program (new_val) ¶

: old_val = info_program (new_val, "local") ¶

Запрос или установка внутренней переменной, определяющей имя программы info, которую нужно запустить.

Значение по умолчанию — info. Значение по умолчанию может быть переопределено переменной среды OCTAVE_INFO_PROGRAM, или аргументом командной строки --info-program NAME.

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

См. также: info_file, doc, help, makeinfo_program.

: val = makeinfo_program () ¶

: old_val = makeinfo_program (new_val) ¶

: old_val = makeinfo_program (new_val, "local") ¶

Запрос или установка внутренней переменной, определяющей имя программы, которую Octave запускает для форматирования текста справки, содержащего теги Texinfo.

Значение по умолчанию — makeinfo.

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

См. также: texi_macros_file, info_file, info_program, doc, help.

: val = texi_macros_file () ¶

: old_val = texi_macros_file (new_val) ¶

: old_val = texi_macros_file (new_val, "local") ¶

Запрос или установка внутренней переменной, которая указывает имя файла, содержащего макросы Texinfo, которые добавляются к строкам документации перед передачей в makeinfo.

Значение по умолчанию — octave-home/share/octave/version/etc/macros.texi, где octave-home — корневой каталог установки Octave, а version — номер версии Octave. Значение по умолчанию может быть переопределено переменной среды OCTAVE_TEXI_MACROS_FILE, или аргументом командной строки --texi-macros-file FNAME.

При вызове изнутри функции с опцией "local", переменная изменяется локально для функции и всех вызываемых ею подпрограмм. Исходное значение переменной восстанавливается при выходе из функции.

См. также: makeinfo_program.

: val = doc_cache_file () ¶

: old_val = doc_cache_file (new_val) ¶

: old_val = doc_cache_file (new_val, "local") ¶

Запрос или установка внутренней переменной, которая указывает имя файла кэша документации Octave.

Файл кэша значительно повышает производительность команды lookfor. Значение по умолчанию — octave-home/share/octave/version/etc/doc-cache, где octave-home — корневой каталог установки Octave, а version — номер версии Octave. Значение по умолчанию может быть переопределено переменной среды OCTAVE_DOC_CACHE_FILE, или аргументом командной строки --doc-cache-file FNAME.

При вызове изнутри функции с опцией "local", переменная изменяется локально для функции и всех вызываемых ею подпрограмм. Исходное значение переменной восстанавливается при выходе из функции.

См. также: doc_cache_create, lookfor, info_program, doc, help, makeinfo_program.

См. также: lookfor.

: val = built_in_docstrings_file () ¶

: old_val = built_in_docstrings_file (new_val) ¶

: old_val = built_in_docstrings_file (new_val, "local") ¶

Запрос или установка внутренней переменной, которая указывает имя файла, содержащего строки документации для встроенных функций Octave.

Значение по умолчанию — octave-home/share/octave/version/etc/built-in-docstrings, где octave-home — корневой каталог установки Octave, а version — номер версии Octave. Значение по умолчанию может быть переопределено переменной среды OCTAVE_BUILT_IN_DOCSTRINGS_FILE, или аргументом командной строки --built-in-docstrings-file FNAME.

Примечание: Эта переменная используется только при инициализации Octave. Изменение ее во время сеанса Octave не окажет никакого влияния.

: val = suppress_verbose_help_message () ¶

: old_val = suppress_verbose_help_message (new_val) ¶

: old_val = suppress_verbose_help_message (new_val, "local") ¶

Запрос или установка внутренней переменной, которая управляет тем, добавляет ли Octave дополнительную информацию о помощи в конце вывода от команды help и сообщениях об использовании для встроенных команд.

При вызове изнутри функции с опцией "local", переменная изменяется локально для функции и всех вызываемых ею подпрограмм. Исходное значение переменной восстанавливается при выходе из функции.

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

: doc_cache_create (out_file, directory) ¶

: doc_cache_create (out_file) ¶

: doc_cache_create () ¶

Генерирует кэш документации для всех функций в directory.

Кэш документации генерируется для всех функций в directory, который может быть одиночной строкой или массивом ячеек строк. Кэш используется для ускорения функции lookfor.

Кэш сохраняется в файле out_file, который по умолчанию равен doc-cache, если не задан.

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

См. также: doc_cache_file, lookfor, path.

: [text, format] = get_help_text (name) ¶

Возвращает исходный текст справки функции name.

Исходный текст справки возвращается в text, а формат — в format. Формат — строка, которая является одной из "texinfo", "html", или "plain text".

См. также: get_help_text_from_file.

: [text, format] = get_help_text_from_file (fname) ¶

Возвращает исходный текст справки из файла fname.

Исходный текст справки возвращается в text, а формат — в format. Формат — строка, которая является одной из "texinfo", "html", или "plain text".

См. также: get_help_text.

: text = get_first_help_sentence (name) ¶

: text = get_first_help_sentence (name, max_len) ¶

: [text, status] = get_first_help_sentence (…) ¶

Возвращает первое предложение текста справки функции.

Первое предложение определяется как текст после объявления функции до первой точки (".") или первого появления двух последовательных символов новой строки ("\n\n"). Текст усекается до максимальной длины max_len, которая по умолчанию равна 80. Если текст должен быть усечен, последние три символа текста заменяются на "...", чтобы указать, что был доступен дополнительный текст.

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

В качестве примера, первое предложение этой справки —

get_first_help_sentence ("get_first_help_sentence")
-| ans = Return the first sentence of a function's help text.