#11815: Embedding information in doc strings must not be formatted
----------------------------+-----------------------------------------------
Reporter: SimonKing | Owner: jason
Type: defect | Status: positive_review
Priority: major | Milestone: sage-4.7.2
Component: misc | Keywords: embedding format
Work_issues: | Upstream: N/A
Reviewer: Volker Braun | Author: Simon King
Merged: | Dependencies: #9976 #11287 #11298 #11342
----------------------------+-----------------------------------------------
Description changed by leif:
Old description:
> A doc string from an extension module typically starts with embedding
> information, such as here:
> {{{
> sage: cython("""
> ....: def testfunc(x):
> ....: 'some doc string'
> ....: return x
> ....: """)
> sage: print testfunc.__doc__
> File: _mnt_local_king__sage_temp_mpc622_13356_tmp_0_spyx_0.pyx (starting
> at line 7)
> some doc string
> }}}
>
> There are two functions in `sage.misc.sageinspect` that retrieve doc
> strings: `sage_getdoc` and `_sage_getdoc_unformatted`. The latter returns
> the doc string as it is, the former is supposed to remove the embedding
> information.
>
> However, before doing so, sage_getdoc runs `sage.misc.sagedoc.format` on
> the output of `_sage_getdoc_unformatted`. That is a problem, because the
> formatting may insert line breaks, thereby destroying the embedding
> information, so that it can now not be correctly stripped from the doc
> string.
>
> I suggest to modify `sage.misc.sagedoc.format`, such that the first line
> is preserved, if it contains embedding information. In that case,
> directives are searched in the second line of the doc string, not in the
> first line (currently the only recognized directive is `nodetex`).
>
> Example, without the patch:
> {{{
> sage: from sage.misc.sagedoc import format
> sage: r = 'File:
> _local_user_with_a_very_long_name_that_would_normally_be_wrapped_sage_temp_machine_name_1234_tmp_1_spyx_0.pyx
> (starting at line 6)\nnodetex\nsome doc for a cython method\n`x \\geq y`'
> sage: print format(r)
> File: _local_user_with_a_very_long_name_that_would_normally_be_wrapped
> _sage_temp_machine_name_1234_tmp_1_spyx_0.pyx (starting at line 6)
> nodetex some doc for a cython method x >= y
> }}}
>
> The same example with the patch (it is a new doc test):
> {{{
> sage: r = 'File:
> _local_user_with_a_very_long_name_that_would_normally_be_wrapped_sage_temp_machine_name_1234_tmp_1_spyx_0.pyx
> (starting at line 6)\nnodetex\nsome doc for a cython method\n`x \\geq y`'
> sage: print format(r)
> File:
> _local_user_with_a_very_long_name_that_would_normally_be_wrapped_sage_temp_machine_name_1234_tmp_1_spyx_0.pyx
> (starting at line 6)
> <BLANKLINE>
> some doc for a cython method
> `x \geq y`
> }}}
New description:
A doc string from an extension module typically starts with embedding
information, such as here:
{{{
sage: cython("""
....: def testfunc(x):
....: 'some doc string'
....: return x
....: """)
sage: print testfunc.__doc__
File: _mnt_local_king__sage_temp_mpc622_13356_tmp_0_spyx_0.pyx (starting
at line 7)
some doc string
}}}
There are two functions in `sage.misc.sageinspect` that retrieve doc
strings: `sage_getdoc` and `_sage_getdoc_unformatted`. The latter returns
the doc string as it is, the former is supposed to remove the embedding
information.
However, before doing so, sage_getdoc runs `sage.misc.sagedoc.format` on
the output of `_sage_getdoc_unformatted`. That is a problem, because the
formatting may insert line breaks, thereby destroying the embedding
information, so that it can now not be correctly stripped from the doc
string.
I suggest to modify `sage.misc.sagedoc.format`, such that the first line
is preserved, if it contains embedding information. In that case,
directives are searched in the second line of the doc string, not in the
first line (currently the only recognized directive is `nodetex`).
Example, without the patch:
{{{
sage: from sage.misc.sagedoc import format
sage: r = 'File:
_local_user_with_a_very_long_name_that_would_normally_be_wrapped_sage_temp_machine_name_1234_tmp_1_spyx_0.pyx
(starting at line 6)\nnodetex\nsome doc for a cython method\n`x \\geq y`'
sage: print format(r)
File: _local_user_with_a_very_long_name_that_would_normally_be_wrapped
_sage_temp_machine_name_1234_tmp_1_spyx_0.pyx (starting at line 6)
nodetex some doc for a cython method x >= y
}}}
The same example with the patch (it is a new doc test):
{{{
sage: r = 'File:
_local_user_with_a_very_long_name_that_would_normally_be_wrapped_sage_temp_machine_name_1234_tmp_1_spyx_0.pyx
(starting at line 6)\nnodetex\nsome doc for a cython method\n`x \\geq y`'
sage: print format(r)
File:
_local_user_with_a_very_long_name_that_would_normally_be_wrapped_sage_temp_machine_name_1234_tmp_1_spyx_0.pyx
(starting at line 6)
<BLANKLINE>
some doc for a cython method
`x \geq y`
}}}
----
Apply [attachment:trac11815_format_must_preserve_embedding.patch] to the
Sage library.
--
--
Ticket URL: <http://trac.sagemath.org/sage_trac/ticket/11815#comment:13>
Sage <http://www.sagemath.org>
Sage: Creating a Viable Open Source Alternative to Magma, Maple, Mathematica,
and MATLAB
--
You received this message because you are subscribed to the Google Groups
"sage-trac" group.
To post to this group, send email to [email protected].
To unsubscribe from this group, send email to
[email protected].
For more options, visit this group at
http://groups.google.com/group/sage-trac?hl=en.
