[RFC,5/5] gpu/doc: Convert to markdown harder
diff mbox

Message ID e67c10e5e36991b4a646fda04a627ef14f1509d3.1444655697.git.lukas@wunner.de
State New
Headers show

Commit Message

Lukas Wunner Oct. 12, 2015, 7:10 a.m. UTC
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@collabora.co.uk>
Signed-off-by: Lukas Wunner <lukas@wunner.de>
---
 include/drm/drm_vma_manager.h | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

Comments

Daniel Vetter Oct. 14, 2015, 1:59 p.m. UTC | #1
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@collabora.co.uk>
> Signed-off-by: Lukas Wunner <lukas@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

>   * are allowed while holding this lock. All other contexts are blocked from VMA
>   * until the lock is released via drm_vma_offset_unlock_lookup().
>   *
> -- 
> 1.8.5.2 (Apple Git-48)
>
Danilo Cesar Lemes de Paula Oct. 14, 2015, 2:04 p.m. UTC | #2
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@collabora.co.uk>
>> Signed-off-by: Lukas Wunner <lukas@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?

Danilo


> 
>>   * are allowed while holding this lock. All other contexts are blocked from VMA
>>   * until the lock is released via drm_vma_offset_unlock_lookup().
>>   *
>> -- 
>> 1.8.5.2 (Apple Git-48)
>>
>
Lukas Wunner Oct. 14, 2015, 3:54 p.m. UTC | #3
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@collabora.co.uk>
> >> Signed-off-by: Lukas Wunner <lukas@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
Daniel Vetter Oct. 14, 2015, 5:03 p.m. UTC | #4
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@collabora.co.uk>
> > >> Signed-off-by: Lukas Wunner <lukas@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

Patch
diff mbox

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
  * are allowed while holding this lock. All other contexts are blocked from VMA
  * until the lock is released via drm_vma_offset_unlock_lookup().
  *