Jun 17, 2008

Addressing Lines in Plain Text Files

Jirka suggested a possibility to enhance YCP documentation with real-life code examples. For that, we'd need to point to numbered lines within the source code. I thought that ViewVC can do it but apparently not (maybe annotate has it, but it is broken at our site). But there is a new generic way: RFC 5147: URI Fragment Identifiers for the text/plain Media Type. Only none of the browsers seems to support it today...

This points to line 13, with the prototype of main:
http://svn.opensuse.org/svn/yast/trunk/libyui/examples/HelloWorld.cc#line=,13

1 comment:

kobliha said...

That's a typical solution exists case! ;) As I've exactly expected...

Frankly, I don't think it's worth the effort to link a real code because of several reasons:

e.g., the code would have to be linked when the documentation is generated, code changes in time but the documentation stays unchanged (don't try to cheat the aunt Death with exact commit numbers or branches)

e.g., someone would still have to chose those relevant parts of code to link or invent some ultra-brutal scripts to find them in SVN and .. well, isn't it just easier to use the @example tag and copy the real code to a built-in / Module / ... documentation?

It's nice you'd like to invest your time and energy to enhancing the YaST documentation but I know dozens of better things to do :) ;)