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 имеют правильное форматирование, но то же самое нельзя гарантировать для внешних пакетов и функций, предоставленных пользователями. Поэтому для поиска связанных функций, не входящих в состав Octave, может потребоваться аргумент "-all".

Скорость поиска значительно повышается при наличии кэшированного файла документации. Дополнительные сведения см. в разделе 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")

Запросить или задать внутреннюю переменную, определяющую имя файла info для 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.