Better RDoc Inline Markup

[Intransition]

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.

 

[Xavier Noria]

RDoc's SimpleMarkup =C2=A0doesn't catch all the cases of =C2=A0inline mar= kup
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:

=C2=A0+ActiveRecord::Base+

=C2=A0+merge!+

=C2=A0+is_a?+

=C2=A0+name=3D+

=C2=A0+object.call+

Another gotcha are symbols:

+:select+

 

[Eric Hodel]

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.

+ is for variables and variables don't have punctuation.

If you *really* want those in <tt> format, use <tt>.

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.)

 

[trans]

+ is for variables and variables don't have punctuation.

If you *really* want those in <tt> format, use <tt>.

RDoc makes classes and (most) methods stand out by turning them into =A0
links. =A0If it doesn't link, adding a # in front should fix it. =A0
(Single-word method calls don't get links by default since that grabs =A0
too many common words.)

SM is used for more than just generating RDocs. For instance, READMEs.

 

[John Barnette]

SM is used for more than just generating RDocs. For instance,
READMEs.

I've been pretty happy using <tt></tt> for inline code examples, no
matter how small, that aren't identifiers. Does this not work for you?


~ j.

 

[trans]

I've been pretty happy using <tt></tt> for inline code examples, no =A0
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 <tags></tags> 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.

 

[Xavier Noria]

MEs.

I've been pretty happy using <tt></tt> for inline code examples, no matte= r
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.

 

[Eric Hodel]

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.

Wait, did you even try it?

$ echo '+ActiveRecord::Base+ +merge!+ +is_a?+ +name=+ +object.call+
+:symbol+' | rdoc --pipe
<p>
+ActiveRecord::Base+ <tt>merge!</tt> <tt>is_a?</tt> <tt>name=</tt>
<tt>object.call</tt> <tt>:symbol</tt>
</p>

They all work in RDoc 2.4.3 except A::B. I even threw in :symbol.

 

[Xavier Noria]

Wait, did you even try it?

$ echo '+ActiveRecord::Base+ +merge!+ +is_a?+ +name=3D+ +object.call+
+:symbol+' | rdoc --pipe
<p>
+ActiveRecord::Base+ <tt>merge!</tt> <tt>is_a?</tt> <tt>name=3D</tt>
<tt>object.call</tt> <tt>:symbol</tt>
</p>

They all work in RDoc 2.4.3 except A::B. =C2=A0I 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.

 

[trans]

Wait, did you even try it?

$ echo '+ActiveRecord::Base+ +merge!+ +is_a?+ +name=3D+ +object.call+ =A0
+:symbol+' | rdoc --pipe
<p>
+ActiveRecord::Base+ <tt>merge!</tt> <tt>is_a?</tt> <tt>name=3D</tt>
<tt>object.call</tt> <tt>:symbol</tt>
</p>

Hmmm...

require 'rdoc/markup/simple_markup'
require 'rdoc/markup/simple_markup/to_html'
p =3D SM::SimpleMarkup.new
h =3D SM::ToHtml.new
puts p.convert('+ActiveRecord::Base+ +merge!+ +is_a?+ +name=3D+
+object.call+ +:symbol+',h)

produces:

<p>
+ActiveRecord::Base+ +merge!+ +is_a?+ +name=3D+ +object.call+ +:symbol
+
</p>

require 'rdoc'
RDoc::VERSION #=3D> "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.

 

[Eric Hodel]

Wait, did you even try it?

$ echo '+ActiveRecord::Base+ +merge!+ +is_a?+ +name=+ +object.call+
+:symbol+' | rdoc --pipe
<p>
+ActiveRecord::Base+ <tt>merge!</tt> <tt>is_a?</tt> <tt>name=</tt>
<tt>object.call</tt> <tt>:symbol</tt>
</p>

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:

[...]

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:

http://rdoc.rubyforge.org/RDoc/Markup.html

 

[trans]

There's no more SM, rdoc 2.x is properly namespaced.
See:

http://rdoc.rubyforge.org/RDoc/Markup.html

Thank you!

BTW, there's old docs out there, in particular:

http://rdoc.sourceforge.net/

And tend to be at the top of Google searches.