RDoc’s SimpleMarkup doesn’t catch all the cases of inline markup
that is really useful for a Ruby documentation. I think it’s checking
for \w+ only, but adding some other punctuation marks would be
helpful. Namely, none of the following work b/c of punctuation marks:
+ActiveRecord::Base+
+merge!+
+is_a?+
+name=+
+object.call+
It would great if the Regexp could be expanded to catch these cases.
Thanks.
On Thu, Sep 3, 2009 at 5:16 PM, Intransition[email protected] wrote:
 +name=+
 +object.call+
Another gotcha are symbols:
+:select+
On Sep 3, 2009, at 08:16, Intransition wrote:
+name=+
+object.call+
It would great if the Regexp could be expanded to catch these cases.
If you really want those in format, use .
RDoc makes classes and (most) methods stand out by turning them into
links. If it doesn’t link, adding a # in front should fix it.
(Single-word method calls don’t get links by default since that grabs
too many common words.)
On Sep 3, 6:17 pm, Eric H. [email protected] wrote:
- is for variables and variables don’t have punctuation.
If you really want those in format, use .
RDoc makes classes and (most) methods stand out by turning them into
links. If it doesn’t link, adding a # in front should fix it.
(Single-word method calls don’t get links by default since that grabs
too many common words.)
SM is used for more than just generating RDocs. For instance, READMEs.
On Sep 3, 6:53 pm, John B. [email protected] wrote:
On Sep 3, 2009, at 3:33 PM, trans wrote:
SM is used for more than just generating RDocs. For instance,
READMEs.I’ve been pretty happy using for inline code examples, no
matter how small, that aren’t identifiers. Does this not work for you?
Not so much. It isn’t very good for all uses. Certain documents are
intended for being read both as the converted HTML and the original
text. And lots of hampers that. I really like RDoc.
Markdown’s handling of indented content is lacking in my opinion.
Moreover I’d rather use a single markup syntax everywhere in my
project, code, README, HISTORY, etc. I don’t mind have to specify a
“turn on extra processing” flag or something when I need it, but it
would be really nice if RDoc could handle a broader range of
documentation markup needs.
On Fri, Sep 4, 2009 at 12:53 AM, John B.[email protected]
wrote:
On Sep 3, 2009, at 3:33 PM, trans wrote:
SM is used for more than just generating RDocs. Â For instance, READMEs.
I’ve been pretty happy using for inline code examples, no matter
how small, that aren’t identifiers. Does this not work for you?
Yeah it works, but ++ would be much simpler and clean.
In fact when docrails started I personally went a cleaned +:symbol+s
and friends, and there’s this gotcha mentioned in the rails docs
guidelines because of it. That’s people’s fault because it is clearly
documented of course, but I think suggests some people indeed expect
that + covers a bit more than \A\w+\z.
I’d certainly vote for supporting the examples that have been
mentioned in the thread.
On Sep 3, 2009, at 08:16, Intransition wrote:
+name=+
+object.call+
It would great if the Regexp could be expanded to catch these cases.
Wait, did you even try it?
$ echo ‘+ActiveRecord::Base+ +merge!+ +is_a?+ +name=+ +object.call+
+:symbol+’ | rdoc --pipe
+ActiveRecord::Base+ merge! is_a? name= object.call :symbol
They all work in RDoc 2.4.3 except A::B. I even threw in :symbol.
On Fri, Sep 4, 2009 at 9:05 PM, Eric H.[email protected] wrote:
Wait, did you even try it?
$ echo ‘+ActiveRecord::Base+ +merge!+ +is_a?+ +name=+ +object.call+
+:symbol+’ | rdoc --pipe+ActiveRecord::Base+ merge! is_a? name= object.call :symbol
They all work in RDoc 2.4.3 except A::B. Â I even threw in :symbol.
Great! Didn’t know it worked in recent rdoc, it is certainly not
documented in doc_root/rdoc-2.4.3/rdoc/RDoc.html that I can tell.
That’s good we are currently migrating Rails docs to 2.4 indeed.
On Sep 4, 3:05 pm, Eric H. [email protected] wrote:
Wait, did you even try it?
$ echo ‘+ActiveRecord::Base+ +merge!+ +is_a?+ +name=+ +object.call+
+:symbol+’ | rdoc --pipe+ActiveRecord::Base+ merge! is_a? name= object.call :symbol
Hmmm…
require ‘rdoc/markup/simple_markup’
require ‘rdoc/markup/simple_markup/to_html’
p = SM::SimpleMarkup.new
h = SM::ToHtml.new
puts p.convert(‘+ActiveRecord::Base+ +merge!+ +is_a?+ +name=+
+object.call+ +:symbol+’,h)
produces:
+ActiveRecord::Base+ +merge!+ +is_a?+ +name=+ +object.call+ +:symbol +
require ‘rdoc’
RDoc::VERSION #=> “2.4.3”
So now I’m thinking RDoc no longer has SM ? And when I require it I am
actually picking up the RDoc built into Ruby 1.8.7, but when I require
‘rdoc’ I’m getting the latest Gem I installed.
On Sep 3, 2009, at 3:33 PM, trans wrote:
SM is used for more than just generating RDocs. For instance,
READMEs.
I’ve been pretty happy using for inline code examples, no
matter how small, that aren’t identifiers. Does this not work for you?
~ j.
On Sep 5, 3:10 am, Eric H. [email protected] wrote:
There’s no more SM, rdoc 2.x is properly namespaced.
See:
Thank you!
BTW, there’s old docs out there, in particular:
And tend to be at the top of Google searches.
On Sep 4, 2009, at 17:59, trans wrote:
Hmmm…
[…]So now I’m thinking RDoc no longer has SM ? And when I require it I am
actually picking up the RDoc built into Ruby 1.8.7, but when I require
‘rdoc’ I’m getting the latest Gem I installed.
There’s no more SM, rdoc 2.x is properly namespaced.
See:
This forum is not affiliated to the Ruby language, Ruby on Rails framework, nor any Ruby applications discussed here.
Sponsor our Newsletter | Privacy Policy | Terms of Service | Remote Ruby Jobs