From ee22f880085876d26461caf6a288649daff5fdac Mon Sep 17 00:00:00 2001 From: Mario Ortiz Manero Date: Tue, 27 Apr 2021 16:34:01 +0200 Subject: [PATCH] add docs for commands --- README.adoc | 30 ++++++++++++++---- doc/adoc_pdf_live.txt | 74 ++++++++++++++++++++++++++++++++++++++++--- ftplugin/asciidoc.vim | 2 +- 3 files changed, 94 insertions(+), 12 deletions(-) diff --git a/README.adoc b/README.adoc index efebf47..fbb4ee3 100644 --- a/README.adoc +++ b/README.adoc @@ -21,28 +21,46 @@ Plug 'marioortizmanero/adoc-pdf-live.nvim' .https://github.com/wbthomason/packer.nvim[packer.nvim] [source, vim] ---- -use 'marioortizmanero/adoc-pdf-live.nvim' +use { + 'marioortizmanero/adoc-pdf-live.nvim', + config = "require('adoc_pdf_live').setup()" +} ---- == Usage -You can setup the plugin with its default configuration with: +You must setup the plugin in order to use it. For the basic setup with the +default options: [source, lua] ---- require('adoc_pdf_live').setup() ---- -Or, to override the default options: +Or, to specify your own custom options: [source, lua] ---- require('adoc_pdf_live').setup { viewer = 'zathura', - params = '-r asciidoctor-mathematical -r asciidoctor-diagram -a mathematical-format=svg' + params = '-r asciidoctor-mathematical -r asciidoctor-diagram -a mathematical-format=svg', style_regex = 'custom-style\\.ya?ml' } ---- -See the configuration section in the documentation for more information of each -option. +See the configuration section in the documentation for more information about +the available options. + +Once you have an AsciiDoc file open, you can use the `:AdocPdfLiveStart` command +to compile the document whenever the file is saved. `:AdocPdfLiveOpen` will +additionally open your preferred PDF viewer, and `:AdocPdfLiveStop` will stop +the plugin. For more commands, see its section in the documentation. + +It's highly recommended to use a PDF viewer like +https://pwmt.org/projects/zathura/[zathura] which automatically reloads the file +when it's modified, so that the live reloading is seamless. + +https://github.com/asciidoctor/asciidoctor-pdf/blob/main/docs/theming-guide.adoc[Yaml +style files] are roughly supported. This plugin will automatically look for one +and enable it when compiling the PDF, with the `style_regex` option. You can +override it with the `style` option or the `:AdocPdfLiveStyle STYLE` command. diff --git a/doc/adoc_pdf_live.txt b/doc/adoc_pdf_live.txt index 37d90a5..a878602 100644 --- a/doc/adoc_pdf_live.txt +++ b/doc/adoc_pdf_live.txt @@ -4,6 +4,14 @@ Author: Mario Ortiz Manero Homepage: License: GPLv3 +============================================================================== +CONTENTS *adoc-pdf-live-contents* + + 1. Introduction..............................................|adoc-pdf-live| + 2. Usage...............................................|adoc-pdf-live-usage| + 3. Commands.........................................|adoc-pdf-live-commands| + 4. Configuration...............................|adoc-pdf-live-configuration| + ============================================================================== INTRODUCTION *adoc-pdf-live* @@ -22,24 +30,80 @@ lots to improve. ============================================================================== USAGE *adoc-pdf-live-usage* - -You can setup the plugin with its default configuration with: +You must setup the plugin in order to use it. For the basic setup with the +default options: > require('adoc_pdf_live').setup() > -Or, to override the default options: +Or, to specify your own custom options: > require('adoc_pdf_live').setup { viewer = 'zathura', - params = '-r asciidoctor-mathematical -r asciidoctor-diagram -a mathematical-format=svg' + params = '-r asciidoctor-mathematical -r asciidoctor-diagram -a mathematical-format=svg', style_regex = 'custom-style\\.ya?ml' } > -See the configuration section for more information of each option. +See the configuration section for more information about the available +options. + +Once you have an AsciiDoc file open, you can use the `:AdocPdfLiveStart` command +to compile the document whenever the file is saved. `:AdocPdfLiveOpen` will +additionally open your preferred PDF viewer, and `:AdocPdfLiveStop` will stop +the plugin. For more commands, see its section in the documentation. + +It's highly recommended to use a PDF viewer like zathura [1] which +automatically reloads the file when it's modified, so that the live reloading +is seamless. + +Yaml style files [2] are roughly supported. This plugin will automatically +look for one and enable it when compiling the PDF, with the `style_regex` +option. You can override it with the `style` option or the `:AdocPdfLiveStyle +STYLE` command. + +[1] https://pwmt.org/projects/zathura/ +[2] https://github.com/asciidoctor/asciidoctor-pdf/blob/main/docs/theming-guide.adoc + +============================================================================== +COMMANDS *adoc-pdf-live-commands* + +|:AdocPdfLiveStart| *:AdocPdfLiveStart* + +Start compiling the document whenever the AsciiDoc file is saved. + +If a style file isn't set, the plugin will try to find one with the configured +regex in the `style-regex` option. + +|:AdocPdfLiveOpen| *:AdocPdfLiveOpen* + +Start compiling the document whenever the AsciiDoc file is saved and open the +configured PDF viewer with it. + +If a style file isn't set, the plugin will try to find one with the configured +regex in the `style-regex` option. + +|:AdocPdfLiveStop| *:AdocPdfLiveStop* + +Stop compiling the document for each save. + +|:AdocPdfLiveStyle| *:AdocPdfLiveStyle* + +Given a style yaml file as a parameter, override the current one with it. + +|:AdocPdfLiveLogs| *:AdocPdfLiveLogs* + +See the logs for the lifetime of the plugin. + +|:AdocPdfLiveDebug| *:AdocPdfLiveDebug* + +Enable debug mode. + +|:AdocPdfLiveNoDebug| *:AdocPdfLiveNoDebug* + +Disable debug mode. ============================================================================== CONFIGURATION *adoc-pdf-live-config* diff --git a/ftplugin/asciidoc.vim b/ftplugin/asciidoc.vim index 053804c..92b11cd 100644 --- a/ftplugin/asciidoc.vim +++ b/ftplugin/asciidoc.vim @@ -11,7 +11,7 @@ if s:adoc_pdf_live.is_configured() command! AdocPdfLiveDebug :call s:adoc_pdf_live.set_debug(1) command! AdocPdfLiveNoDebug :call s:adoc_pdf_live.set_debug(1) " Set the style file - command! -nargs=1 AdocPdfStyle :call s:adoc_pdf_live.set_style('') + command! -nargs=1 AdocPdfLiveStyle :call s:adoc_pdf_live.set_style('') " Show the logs command! AdocPdfLiveLogs :call s:adoc_pdf_live.show_logs()