Code Blocks Extension for filenames and line numbers

I’d like to put forward a proposal to extend code blocks to include a filename, to be used as a caption for the code block, and a starting line number.

##Proposal 1##

filename.ext:starting_line_number
or:
/path/to/filename.cpp:100

This proposal is similar to the output of grep and the breakpoint notation in gdb

```filename.cpp:100
int main(){
    return 0;
}
```

###Proposal 2###

This proposal should allow backwards computability with older documents/parsers.

class filename.ext:starting_line_number

```cpp  filename.cpp:100
int main(){
    return 0;
}
```

###Proposal 3###

class filename=filename.cpp linenumber=staring_line_number foo=bah ...

This final proposal allows for future extensions to be added, while remaining compatible with other parsers that only support a limited number of features. (This is personally my least preferred option but I could see it being useful to someone).

```cpp  filename=filename.cpp linenumber=100
int main(){
    return 0;
}
```

##Proposed Output:##

100: int main(){
101:     return 0;
102: }

                           filename.cpp
1 Like

This seems like a good fit for the generic directives/plugins syntax as well. For example:

@@@code[caption](filename.cpp:100){.class}
int main(){
    return 0;
}
@@@

Or you could probably get away with the attribute syntax and run some post-processor to get the desired output:

``` {.class caption=filename.cpp linenumber=100}
int main(){
    return 0;
}
```
3 Likes

Probably the generic directives would use a linenum attribute.

@@@code[c](filename.c){linenum=100}
int main() {
    return 0;
}
@@@

The attribute syntax looks neat an wonderfully compatible.

I was typing up instructions in plain text, and noticed that I wanted to add some title message to it. Anyway this is what I noticed that I did spontaneously (stylewise), without referencing any instructions.

```c : hello world program
#include <stdio.h>
int main(void){
   printf("Hello, world!\n");
}
```

So if I am to include filename and line number. It might look like

```helloworld.c:4 : hello world program
#include <stdio.h>
int main(void){ printf("Hello, world!\n"); }
```
```c:4 : hello world program
#include <stdio.h>
int main(void){ printf("Hello, world!\n"); }
```
```helloworld.c : hello world program
#include <stdio.h>
int main(void){ printf("Hello, world!\n"); }
```

But that’s mostly because I find the : to be easier to reach. But if stylistic consistency to markdown is desired… then maybe # is better, because of it’s use as header text.

```helloworld.c:4 # hello world program
#include <stdio.h>
int main(void){ printf("Hello, world!\n"); }
```
```c:4 # hello world program
#include <stdio.h>
int main(void){ printf("Hello, world!\n"); }
```
```helloworld.c # hello world program
#include <stdio.h>
int main(void){ printf("Hello, world!\n"); }
```

Ultimately outputting similar to rtcfirefly, but with heading text as well

|            filename.cpp : hello world program               |
100: int main(){
101:     return 0;
102: }

tl;dr: Would like heading text to be included, in addition to filename and line number. Makes relocation of code sections easier.

You can already do something like this with the existing syntax and reference parsers. The whole “info string” in a backtick code block is stored. So, you just need to traverse the AST, looking for code blocks with an info string that matches certain criteria, and replace their contents with lines read from a file.

If I needed this feature, I’d probably put the filename and lines in the code block itself, with a syntax like

``` cpp include
[helloworld.cpp:4-16]
Caption here
```

This would also degrade nicely if you viewed it on github or something.

I see jgm , so if I am getting what you are saying:

``` cpp include
[helloworld.cpp:4-16]
Caption here
```
```
#include <iostream>
int main(){
    std::cout << "Hello, world!\n";
}
```

Would degrade like:

[helloworld.cpp:4-16]
Caption here
#include <iostream>
int main(){
    std::cout << "Hello, world!\n";
}

The colon : is frequently used between file name and line number in compiler logs etc., but a more URL-like notation would use a hash sign, e.g. filename.cpp#l=100-104 or just filename.cpp#100-104.

Since Commonmark doesn’t say anything normative about the format of the info string after the opening fence, we could well assume that file extension and language or class would be aliases of each other if they are not equal in the first place. The file name would become an optional attribute before the dot that is otherwise optional as well. That’s basically OP Proposal 1.

```cpp
```.cpp
```filename.cpp

A parser could create a “save as” link for code blocks that would use the file name provided by the author as a suggested file name on the reader’s system. Otherwise it would be informative only, maybe appear in a caption.

Transcluding source files or parts thereof, like @jgm’s example seems to do, is related indeed and this requires a resource name.

1 Like

this is absolutely what I came here to propose. Boo that it has’t been put into the spec yet.

I specifically like @mofosyne second option, though I think the headings is kind of unnecessary. I dislike the idea of putting the filename/lines in the codeblock itself in part because I think in general that would make parsing from where the actual code starts harder. also might be nice to optionally include a link for stuff.

fully dressed, a space would delimit to the filename / additional parsing

```json [package.json:4-16](https://github...)
 {
   "hello":"world"
 }
 ```

the language type and url should be optional, the former is only for backwards compatibility in existing implementations, this should also be valid.

```json [package.json:4-16](https://github...)
{
   "hello":"world"
}
```

obviously there are already existing implementations of this, so I think at minimum this should be spec-ed

```json
{
   "hello":"world"
}
```

also additional language metadata would be nice, maybe, my biggest reason for this is stacktraces and logs which might be able to be rendered better with additional metadata. though tbh, I don’t really expect to get this.

```stacktrace=java
...
```
```log=log4j,format=fmtstring
```

which could also

```language=java
```

with syntax highlighting required if possible (I suggest requiring a syntax highlighting library, or making it a strong suggestion). I suggest that having the filename formatted the same as if backtics were included part of the spec. Also there should be a requirement that printed line numbers not be part of the same structure so you can copy and paste the code without copy and pasting them.

<sub><code><a href="https://github.com">package.json:5-6</a></code></sub>
<ul>
   <li>5</li>
   <li>6</li>
<li>
<code>
{
   "hello": "world"
}
</code>
</div>

I agree on, it’s a nice and clean syntax

```json [package.json:4-16](https://github...)
{
    "hello": "world"
}
```

Not so big a fan of the other metadata tags you talking about, why would you write language=java when the normal syntax already has support for language specification?