[Intel-gfx] [maintainer-tools PATCH] dim.rst: Document aliases extension on dimrc.

[Jani Nikula]

On Mon, 21 Aug 2017, Rodrigo Vivi <rodrigo.vivi at gmail.com> wrote:
> On Mon, Aug 21, 2017 at 1:39 AM, Jani Nikula <jani.nikula at intel.com> wrote:
>> On Fri, 18 Aug 2017, Rodrigo Vivi <rodrigo.vivi at intel.com> wrote:
>>> On my own workflow I was missing a way to download mboxes
>>> directly from patchwork with the patchwork id. So my first
>>> reflex was to modify dim to fulfil my needs. However that
>>> was increasing dim in complexity and dependencies and leaving
>>> that messy.
>>>
>>> That was when Jani suggested me the dimrc extension with the
>>> example that is now part of this spec.
>>>
>>> That was clean and simple enough to understand, so Daniel
>>> suggested me to add it to the spec.
>>>
>>> For record let's put my final local solution that lays now on
>>> my own ~/.dimrc
>>>
>>> dim_pwaq()
>>> {
>>>       if [ -n "$1" ]; then
>>>               curl https://patchwork.freedesktop.org/patch/$1/mbox/ | dim_apply_queued
>>>       else
>>>       echo "Give me a patchwork id"
>>>       fi
>>> }
>>>
>>> v2: Use code-block directive. Get's cleaner and make check happy.
>>
>> Huh?! For me, this patch leads to:
>>
>> rst2man --strict --no-raw dim.rst >/dev/null
>> NotImplementedError: docutils.writers.manpage.Translator visiting unknown node type: inline
>> Exiting due to error.  Use "--traceback" to diagnose.
>> Please report errors to <docutils-users at lists.sf.net>.
>> Include "--traceback" output, Docutils version (0.13.1 [release]),
>> Python version (2.7.13)
>
> my version here is:
> $ rst2man --version
> rst2man (Docutils 0.14, Python 2.7.6, on linux2)
>
> and I get no complain on this :(

I've got

rst2man (Docutils 0.13.1 [release], Python 2.7.13, on linux2)

which baffles me a bit.

>
>> , your OS type & version, and the
>> command line used.
>> Makefile:49: recipe for target 'mancheck' failed
>> make: *** [mancheck] Error 1
>>
>> The issue here is that even after the "sphinxification" we need to have
>> the man pages render using rst2man to have them work properly via 'dim
>> help'. The ".. code-block::" directive is, AFAICT, a sphinxism.
>
> hm... that makes sense anyway...
> do you know how we could skip in a way that rst2man and sphinx would
> both be happy?

Just add :: at the end of the preceding paragraph:

It is possible to create your own dim helper and aliases by adding them
to \$HOME/.dimrc::

    and add the example in an indented block


>
>>
>>> Cc: Jani Nikula <jani.nikula at intel.com>
>>> Cc: Daniel Vetter <daniel.vetter at ffwll.ch>
>>> Signed-off-by: Rodrigo Vivi <rodrigo.vivi at intel.com>
>>> ---
>>>  dim.rst | 18 ++++++++++++++++++
>>>  1 file changed, 18 insertions(+)
>>>
>>> diff --git a/dim.rst b/dim.rst
>>> index 802c776e03f9..d8c9d728dc7b 100644
>>> --- a/dim.rst
>>> +++ b/dim.rst
>>> @@ -441,6 +441,24 @@ usage
>>>  Short form usage help listing all subcommands. Run by default or if an unknown
>>>  subcommand was passed on the cmdline.
>>>
>>> +ALIASES
>>> +=======
>>> +
>>> +Extending **dim** functionalities
>>> +---------------------------------
>>> +
>>> +It is possible to create your own dim helper and aliases by adding them to \$HOME/.dimrc
>>> +
>>> +.. code-block:: bash
>>> +
>>> +             dim_my_fancy_list_aliases()
>>> +             {
>>> +                     echo "Hello world!":
>>> +                     dim_list_aliases:
>>
>> Why the colons at the end?
>
> duh! probably forgot from one of attempts to use a block without complain...
>
>>
>> BR,
>> Jani.
>>
>>> +             }
>>> +
>>> +             dim_alias_list_aliases=my-fancy-list-aliases
>>> +
>>>  ENVIRONMENT
>>>  ===========
>>
>> --
>> Jani Nikula, Intel Open Source Technology Center
>> _______________________________________________
>> Intel-gfx mailing list
>> Intel-gfx at lists.freedesktop.org
>> https://lists.freedesktop.org/mailman/listinfo/intel-gfx

-- 
Jani Nikula, Intel Open Source Technology Center