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

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

: help name

: help --list

: help .

: help

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

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

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

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

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

Команда help может предоставлять информацию о большинстве операторов, но name необходимо заключать в одинарные или двойные кавычки, чтобы предотвратить обработку name интерпретатором Octave. Например, 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)

: 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)

: 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)

: 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-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)

: 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)

: built_in_docstrings_file (new_val, "local")

Получение или установка внутренней переменной, определяющей имя файла с docstrings для встроенных функций 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")

Получение или установку внутренней переменной, контролирующей добавление дополнительной информации о помощи в конце вывода команды 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.