search

jbranchaud / ocelot

Because you're awesome!
4 stars 1 forks source link

File notation in the Markdown annotation should be wrapped in some kind of 'brackets'. #3

Closed jbranchaud closed 11 years ago

jbranchaud commented 11 years ago

As we move towards a mainly markdown format for Ocelot, I think we should make sure we wrap the file notation (in the subheadings) with some sort of brackets (e.g. curly brackets { and }). The current approach looks like this:

## Shape.java|Square.java

However, I do not believe this is enough. I think we need to add the curly brackets as well like this:

## {Shape.java|Square.java}

If this latter notation is used, then we are able to have more markdown in our markdown (and I heard you wanted more markdown in your markdown). For instance, the committer can write markdown subheadings that are not necessarily ocelot file notation:

## Some sub heading
writing about the topic of the subheading
## {ocelot.rb}
writing about this file in the file notation

This ultimately leaves ocelot to be more flexible and extensible. That seems like a good thing to me at this stage!

jurgns commented 11 years ago

Yo dawg, I heard you like markdown...

Anyway, I'm actually leaning towards the use of a new leading sequence (ie: header levels). The bracket notation could then be used to describe more complex relations.

For example, a commit message sequence for one file would be like so (the leading sequence can obviously be changed):

? Shape.java
something goes here...

A sequence describing two files:

? Shape.java|Square.java
something goes here...

And a more complex relation:

? {Circle.java|Square.java}=>Shape.java
something goes here...

What are your thoughts?

jbranchaud commented 11 years ago

After our talk today, I feel like what we are wanting to do is extend markdown without necessarily taking it over. If our notation requires every subheading to be the file notation (all or nothing), then we are limiting what can be done. With that in mind, I think we want the brackets from the get go in order to signify that the particular heading is the file notation.

As for the brackets being used to represent more complex relations. I think we can do this in addition to the brackets by using parentheses (see Grouped Artifacts).

Does this mesh with our earlier conversation or am I off?

jurgns commented 11 years ago

Closing this in favor of discussion on issue #4