Dima Pasechnik writes:
> only a small minority of Sage users actually use terminal.
How do you know that? Seriously, I'd like to know how our users
distributed across interfaces. It's my impression that quite a lot of
casual users of Sage begin with terminal use and never leave it.
> And in any event, demanding a bibliography reference in terminal is
> a bit over the top (even people who live in terminal, like me, would use a
> web browser to
> look at references, and thus use HTML documentation).
Why? The documentation could automatically create a REFERENCE block at
the end of any method/function/etc. with the bibliographic information
of works cited in that doc string.
> I also totally don't see a value of having a reference to the same thing in
> every file. You can use grep if you must not leave the terminal.
> Also, in Sage, you can use search_src("\[HP\]\ " to find a place [HP] is
> defined:
The value is that, as a user, when I press "myfunc?<tab>" I can *see*
what the reference means without having to spend time and mental effort
grep'ing or search_src'ing. Ask a user what he prefers.
> please don't... this breaks HTML docs badly.
How? I might be wrong (I clearly don't understand Sphinx well), but it
seems that all it breaks is that no hyperlink appears -- but I don't
need that since the bib-information is *right there*.
What worries me most is that it leads to possibly mutually
inconsistent versions of the same bib-information spread all over the
place.
> you are welcome - it's indeed sometimes not easy to find these errors.
> But do feel free to ask pointed questions if you get stuck.
Thanks. I've been working on #20908 and it seems that modifying
an index.rst file leads more often to corruption (and hence `make
doc-build && make`) than most other modifications. That or I am just
unlucky...
> I agree that speeding up this is very important for smoother development.
> Only it seems that our options are not very broad here, unless we get
> involved in speeding it up ourselves....
My conclusion too, after browsing the competition. What I don't
understand is that "Sphinx bad performance" reveals almost no useful
discussions on Google. I would think Sphinx was used on all large Python
projects. Could it be that the way we are calling Sphinx leads to bad
performance?
Travis Scrimshaw writes:
> I don't think so. How else could you resolve a reference in a separate
> file? It would likely lead to a lot of duplication of reference information
> because of this.
> ...
> It depends on what you want to achieve. We currently do all 3 in Sage and
> none of them doesn't cause any problems.
Agreed, unique bib-information is Good(tm); that's why many of us use
BibTeX and possibly Zotero or similar tools. It's just that Sphinx's
incarnation of this is not very smart: the bibliographic information
ends up in a random source file. As a user, I would be confused by
clicking in the doc of module A on some citation, and ending up in the
doc of mostly unrelated module B.
> It depends on what you want to achieve. We currently do all 3 in Sage and
> none of them doesn't cause any problems.
Is the extra negation intentional? What we currently do in Sage is
inconsistent, has lots of duplication of reference information, is not
user-friendly in the way I just described *and* is badly documented. Is
this not a problem?
Best,
Johan
--
You received this message because you are subscribed to the Google Groups
"sage-devel" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to sage-devel+unsubscr...@googlegroups.com.
To post to this group, send email to sage-devel@googlegroups.com.
Visit this group at https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.
