#15009: formatting of references
---------------------------------+-----------------------------
Reporter: eisermbi | Owner:
Type: defect | Status: needs_review
Priority: major | Milestone: sage-5.12
Component: documentation | Resolution:
Keywords: | Merged in:
Authors: | Reviewers:
Report Upstream: N/A | Work issues:
Branch: | Dependencies:
Stopgaps: |
---------------------------------+-----------------------------
Changes (by eisermbi):
* status: new => needs_review
Old description:
> There seems to be some bug in the HTML generation... The docstring of the
> function {{{RandomGNP}}} in the file "sage/graphs/generators/random.py"
> contains
>
> {{{
> REFERENCES:
>
> .. [1] P. Erdos and A. Renyi. On Random Graphs, Publ. Math. 6, 290
> (1959).
>
> .. [2] E. N. Gilbert. Random Graphs, Ann. Math. Stat., 30, 1141
> (1959).
>
> .. [3] V. Batagelj and U. Brandes. Efficient generation of large
> random networks. Phys. Rev. E, 71, 036113, 2005.
>
> }}}
>
> Calling {{{./sage --docbuild reference html}}} creates the following
> output
> with *unequal and wide* spacing (file:
> "doc/output/html/en/reference/graphs/sage/graphs/graph_generators.html"):
>
> {{{
> <p>REFERENCES:</p>
> <table class="docutils footnote" frame="void" id="id12" rules="none">
> <colgroup><col class="label" /><col /></colgroup>
> <tbody valign="top">
> <tr><td class="label">[1]</td><td><ol class="first last upperalpha
> simple" start="16">
> <li>Erdos and A. Renyi. On Random Graphs, Publ. Math. 6, 290 (1959).</li>
> </ol>
> </td></tr>
> </tbody>
> </table>
> <table class="docutils footnote" frame="void" id="id13" rules="none">
> <colgroup><col class="label" /><col /></colgroup>
> <tbody valign="top">
> <tr><td class="label">[2]</td><td><ol class="first last upperalpha
> simple" start="5">
> <li><ol class="first upperalpha" start="14">
> <li>Gilbert. Random Graphs, Ann. Math. Stat., 30, 1141 (1959).</li>
> </ol>
> </li>
> </ol>
> </td></tr>
> </tbody>
> </table>
> <table class="docutils footnote" frame="void" id="id14" rules="none">
> <colgroup><col class="label" /><col /></colgroup>
> <tbody valign="top">
> <tr><td class="label"><a class="fn-backref"
> href="#id11">[3]</a></td><td>V. Batagelj and U. Brandes. Efficient
> generation of large
> random networks. Phys. Rev. E, 71, 036113, 2005.</td></tr>
> </tbody>
> </table>
> }}}
>
> Replacing ".." with "-" (e.g. {{{ .. [1] P. Erdos }}} by {{{ - [1] P.
> Erdos }}}; as it is used in the docstring of the method {{{LCFGraph}}} in
> "sage/graphs/generators/families.py") will yield the following compiler
> error:
>
> {{{
> docstring of sage.graphs.graph_generators.GraphGenerators.RandomGNP:12:
> ERROR: Unknown target name: "3".
> }}}
>
> Nevertheless the output ''looks'' alright in the browser (but item 3 has
> different HTML code):
>
> {{{
> <p>REFERENCES:</p>
> <ul>
> <li><p class="first">[1] P. Erdos and A. Renyi. On Random Graphs, Publ.
> Math. 6, 290 (1959).</p>
> </li>
> <li><p class="first">[2] E. N. Gilbert. Random Graphs, Ann. Math. Stat.,
> 30, 1141 (1959).</p>
> </li>
> <li><dl class="first docutils">
> <dt>[3] V. Batagelj and U. Brandes. Efficient generation of large</dt>
> <dd><p class="first last">random networks. Phys. Rev. E, 71, 036113,
> 2005.</p>
> </dd>
> </dl>
> </li>
> </ul>
> }}}
>
> ----
>
> Furthermore, if only a docstring of a file in "sage/graphs/generators/"
> is changed and {{{./sage -b}}} is run, then {{{./sage --docbuild
> reference html}}} does '''not''' recognize the docstring change. My
> workaround is to make a modification to "sage/graphs/graph_generators.py"
> each time to trigger the necessity of a rebuild of the html reference.
New description:
There seems to be some bug in the HTML generation... The docstring of the
function {{{RandomGNP}}} in the file "sage/graphs/generators/random.py"
contains
{{{
REFERENCES:
.. [1] P. Erdos and A. Renyi. On Random Graphs, Publ. Math. 6, 290
(1959).
.. [2] E. N. Gilbert. Random Graphs, Ann. Math. Stat., 30, 1141
(1959).
.. [3] V. Batagelj and U. Brandes. Efficient generation of large
random networks. Phys. Rev. E, 71, 036113, 2005.
}}}
Calling {{{./sage --docbuild reference html}}} creates some output with
unequal and wide spacing (file:
"doc/output/html/en/reference/graphs/sage/graphs/graph_generators.html").
'''Update''': As mentioned in the comments this behaviour is alright but
the reference names should not be numbers.
On the other hand, if a simple list (entries starting with "-") is used
instead of a proper reference list (entries starting with "..") then the
square brackets like "[1]" do not have any function and one cannot use
them as reference links in the text (e.g. "[1]_"). Hence, for a simple
list, numbers in square brackets might be left out.
----
- This patch changes reference names in {{{sage/graphs}}} from numbers to
proper names if they are used by reference links.
- It also revises the docstrings of the {{{cluster*}}} functions in
"generic_graph.py" (as suggested in the comments).
- Furthermore, it do not seem to be standard that the execution flag of
{{{*.py}}} files is set. Hence, they are removed from
"sage/graphs/generators/families.py" and
"sage/graphs/graph_generators.py".
----
Just a side note: If only a docstring of a file in
"sage/graphs/generators/" is changed and {{{./sage -b}}} is run, then
{{{./sage --docbuild reference html}}} does ''not'' recognize the
docstring change. My workaround is to make a modification to
"sage/graphs/graph_generators.py" each time to trigger the necessity of a
rebuild of the html reference.
--
--
Ticket URL: <http://trac.sagemath.org/ticket/15009#comment:4>
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 unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
To post to this group, send email to [email protected].
Visit this group at http://groups.google.com/group/sage-trac.
For more options, visit https://groups.google.com/groups/opt_out.
