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

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

help имя

help --list

help .

help

Отобразить текст справки для имя.

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

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

При заданном единственном аргументе ., отобразить список всех операторов, доступных в текущей сессии Octave.

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

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

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

doc имя_функции

doc

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

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

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

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

См. также: help.

lookfor строка

lookfor -all строка

[fcn, help1str] = lookfor (строка)

[fcn, help1str] = lookfor ("-all", строка)

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

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

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

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

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

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

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

news

news пакет

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

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

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

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

info ()

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

warranty ()

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

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

val = info_file ()

old_val = info_file (new_val)

info_file (new_val, "local")

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

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

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

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

val = info_program ()

old_val = info_program (new_val)

info_program (new_val, "local")

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

Значение по умолчанию — путь_к_octave/libexec/octave/версия/exec/архитектура/info, где путь_к_octave — корневой каталог установки Octave, версия — номер версии Octave, а архитектура — тип системы (например, i686-pc-linux-gnu). Значение по умолчанию может быть переопределено переменной среды OCTAVE_INFO_PROGRAM, или аргументом командной строки --info-program NAME.

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

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

val = makeinfo_program ()

old_val = makeinfo_program (new_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)

texi_macros_file (new_val, "local")

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

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

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

См. также: makeinfo_program.

val = doc_cache_file ()

old_val = doc_cache_file (new_val)

doc_cache_file (new_val, "local")

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

Файл кэша значительно улучшает производительность команды lookfor. Значение по умолчанию — путь_к_octave/share/octave/версия/etc/doc-cache, где путь_к_octave — корневой каталог установки Octave, а версия — номер версии 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)

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)

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.