[PATCH RFC 5/5] gpu/doc: Convert to markdown harder

[Lukas Wunner]

Hi,

On Wed, Oct 14, 2015 at 11:04:37AM -0300, Danilo Cesar Lemes de Paula wrote:
> On 10/14/2015 10:59 AM, Daniel Vetter wrote:
> > On Mon, Oct 12, 2015 at 09:10:33AM +0200, Lukas Wunner wrote:
> >> This snippet...
> >>
> >>     * Lock VMA manager for extended lookups. Only *_locked() VMA function calls
> >>     * are allowed while holding this lock. All other contexts are blocked from VMA
> >>     * until the lock is released via drm_vma_offset_unlock_lookup().
> >>
> >> ...causes markdown-enabled kernel-doc to barf:
> >>
> >>     debian/build/build-doc/Documentation/DocBook/gpu.aux.xml:3247: parser error : Opening and ending tag mismatch: emphasis line 3247 and function
> >>        *<function><emphasis>locked</function> VMA function calls are allowed while
> >>                                              ^
> >>     /root/airlied/debian/build/build-doc/Documentation/DocBook/gpu.aux.xml:3249: parser error : Opening and ending tag mismatch: function line 3249 and emphasis
> >>        released via <function>drm</emphasis>vma_offset_unlock_lookup</function>.
> >>                                             ^
> >>     unable to parse /root/airlied/debian/build/build-doc/Documentation/DocBook/gpu.aux.xml
> >>
> >> A quick workaround is to replace *_locked() by X_locked().
> >>
> >> Cc: Danilo Cesar Lemes de Paula <danilo.cesar at collabora.co.uk>
> >> Signed-off-by: Lukas Wunner <lukas at wunner.de>
> >> ---
> >>  include/drm/drm_vma_manager.h | 2 +-
> >>  1 file changed, 1 insertion(+), 1 deletion(-)
> >>
> >> diff --git a/include/drm/drm_vma_manager.h b/include/drm/drm_vma_manager.h
> >> index 2ca44db..c1e41b8 100644
> >> --- a/include/drm/drm_vma_manager.h
> >> +++ b/include/drm/drm_vma_manager.h
> >> @@ -97,7 +97,7 @@ drm_vma_offset_exact_lookup(struct drm_vma_offset_manager *mgr,
> >>   * drm_vma_offset_lock_lookup() - Lock lookup for extended private use
> >>   * @mgr: Manager object
> >>   *
> >> - * Lock VMA manager for extended lookups. Only *_locked() VMA function calls
> >> + * Lock VMA manager for extended lookups. Only X_locked() VMA function calls
> > 
> > I went with a plain _unlocked since the X_unlocked looked a bit strange.
> > Anyway Dave acked the rename idea on irc, so all applied. Well except
> > patch 1, there wasn't any conflict when I pushed this to drm-misc.
> > -Daniel
> 
> I didn't test it (not a big fan of doing this), but \* or \_ should
> escape the sequence. Did you consider that?

I did test \* and it didn't help.
I can't remember if I also tested \_.

In any case the issue is not the asterisk but rather that the
underscore in *_locked() is interpreted as the beginning of an
_emphasis_. It seems any underscore at the beginning of a word is
interpreted like that. The question is why the leading asterisk is
not interpreted as the actual beginning of the word. Replacing the
asterisk with an alphabetic character solved it.

Best regards,

Lukas