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.