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

[Daniel Vetter]

On Wed, Oct 14, 2015 at 05:54:31PM +0200, Lukas Wunner wrote:
> 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.

Ok, missed that, so now we have just "locked" instead of "_locked()".
-Daniel
-- 
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch