- About Scala
- Documentation
- Code Examples
- Software
- Scala Developers
ScalaDoc, quotes for monospace text and brokenness
Sat, 2011-04-16, 22:35
Hi everyone,
after asking around in #scala, it seems that the `foo'-style of
quoting is a legacy alternative to the `foo`-style currently in use.
Due to the overall brokenness of `foo' (breaks formatting in certain
places) I really wonder if there is a reason for its existence.
If there is none, there a two alternatives: Either replacing it by the
`foo` style in use now or repurposing `foo' to some other, different
semantic meaning.
I don't really know how powerful the links [[scala.AnyRef]] are
currently (if they still need the full package path for instance) and
if there is already some way to link to specific methods relaibly
(even in case of overloading).
One new purpose for `foo' could be linking to things (e. g. methods)
on the same ScalaDoc page. Example: @deprecated("Usage of
`foo.bar("baz")` is deprecated, use `blubb(String, Int)' instead.")
While I'm not able to implement that feature, I would invest the time
to work on replacing/verifying the usages of `foo' within the standard
library.
There are more than 2000 usages in the standard library, so I don't
really want to touch things twice ... but it is one of the things
which I want to get fixed soon. The state of e. g.
http://www.scala-lang.org/archives/downloads/distrib/files/nightly/docs/library/scala/collection/immutable/List$.html isn't really bearable to me
...
Any comments?
Thanks and bye!
Simon
Sat, 2011-04-16, 23:57
#2
Re: ScalaDoc, quotes for monospace text and brokenness
On 4/16/11 3:37 PM, Michael Bayne wrote:
> I can't imagine that it's anything but an artifact of authors who are
> used to quoting things using ``TeX style''. This is well and good when
> writing papers, but clearly inappropriate in wiki-formatted
> documentation. If one is simply singly- or doubly-quoting text, using
> "double quotes" or 'single quotes' avoids formatting mishaps, and when
> one means to render text in code-style, it should be enclosed in
> `backticks`.
And then look at all these other variations I found implied in the
source. Have you '''triple-single-quoted''' for emphasis today? (I
should have put "triple-single-quoted" in double quotes[1].)
def inline0(): Inline = {
if (char == safeTagMarker) {
val tag = htmlTag()
HtmlTag(tag.data + readHTMLFrom(tag))
}
else if (check("'''")) bold()
else if (check("''")) italic()
else if (check("`")) monospace()
else if (check("__")) underline()
else if (check("^")) superscript()
else if (check(",,")) subscript()
else if (check("[[")) link()
else {
readUntil { char == safeTagMarker || check("''") || char ==
'`' || check("__") || char == '^' || check(",,") || check("[[") ||
isInlineEnd || checkParaEnded || char == endOfLine }
Text(getRead())
}
}
[1] Sweet.
Sun, 2011-04-17, 00:57
#3
Re: ScalaDoc, quotes for monospace text and brokenness
Hi everyone.
>> I can't imagine that it's anything but an artifact of authors who are
>> used to quoting things using ``TeX style''. This is well and good when
>> writing papers, but clearly inappropriate in wiki-formatted
>> documentation. If one is simply singly- or doubly-quoting text, using
>> "double quotes" or 'single quotes' avoids formatting mishaps, and when
>> one means to render text in code-style, it should be enclosed in
>> `backticks`.
I filed http://lampsvn.epfl.ch/trac/scala/ticket/4490 and commited the
changes which should kill 90% of the usages:
https://github.com/soc/scala/tree/ticket/4490
The next thing I'll have a look at will be ``foo''.
I'm not really comfortable replacing it with " ... I would prefer
using the “proper” quotes.
Thanks and good night!
Simon
On Sat, Apr 16, 2011 at 2:35 PM, Simon Ochsenreither
wrote:
> Due to the overall brokenness of `foo' (breaks formatting in certain places)
> I really wonder if there is a reason for its existence.
I can't imagine that it's anything but an artifact of authors who are
used to quoting things using ``TeX style''. This is well and good when
writing papers, but clearly inappropriate in wiki-formatted
documentation. If one is simply singly- or doubly-quoting text, using
"double quotes" or 'single quotes' avoids formatting mishaps, and when
one means to render text in code-style, it should be enclosed in
`backticks`.