Use Formatter for documentation code block

[Yordis Prieto]

It would be nice if `mix format` could take into consideration the comments as well.

Would parse for 

```elixir

```

and then extract the code and format it

What do you think about it

[Louis Pilfold]

Hi Yordis

Might I suggest implementing this as a library that provides a new mix task?  `mix format.markdown` perhaps? Or an escript alternatively.

This way people can make use of this feature today, and then if there proves to be real value it could possibly be integrated later. If the benefit is only niche then people can continue to use it as a library. :)

Cheers,

Louis

--
You received this message because you are subscribed to the Google Groups "elixir-lang-core" group.
To unsubscribe from this group and stop receiving emails from it, send an email to elixir-lang-co...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/elixir-lang-core/a93b4c72-d749-479e-8fd0-48560f306615%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[José Valim]

My concern is that it is best if the documentation does not have the ```elixir tags, since from context, it is expected that most code is written in Elixir. The notation just adds noise. One should prefer to indent by 4 spaces.

On the other hand, formatting of the code indented by four spaces requires partial implementation of a markdown processor and that sounds a bit outside of the scope of the formatter.

José Valim

www.plataformatec.com.br

Founder and 

Director of R&D

--

You received this message because you are subscribed to the Google Groups "elixir-lang-core" group.

To unsubscribe from this group and stop receiving emails from it, send an email to elixir-lang-core+unsubscribe@googlegroups.com.

[Yordis Prieto]

I am using ```elixir because if I have some package where I want to include some other code nothing will prevent me to do it and ExDoc could pick it up the syntax (maybe)

This is the first time I hear about 4 spaces :D

> On the other hand, formatting of the code indented by four spaces requires partial implementation of a markdown processor and that sounds a bit outside of the scope of the formatter.

Maybe `mix formatter.docs` where you try to help the code blocks of the documentation,

I am trying to remove the friction of writing the doc, I found myself getting stock with the details of parenthesis and all of those concerns which I do not pay attention anymore because of formatter

On Monday, January 22, 2018 at 12:07:53 PM UTC-8, José Valim wrote:

My concern is that it is best if the documentation does not have the ```elixir tags, since from context, it is expected that most code is written in Elixir. The notation just adds noise. One should prefer to indent by 4 spaces.

On the other hand, formatting of the code indented by four spaces requires partial implementation of a markdown processor and that sounds a bit outside of the scope of the formatter.

José Valim

www.plataformatec.com.br

Founder and 

Director of R&D

On Mon, Jan 22, 2018 at 8:17 PM, Yordis Prieto <yordis...@gmail.com> wrote:

It would be nice if `mix format` could take into consideration the comments as well.

Would parse for 

```elixir

```

and then extract the code and format it

What do you think about it

--
You received this message because you are subscribed to the Google Groups "elixir-lang-core" group.

To unsubscribe from this group and stop receiving emails from it, send an email to elixir-lang-co...@googlegroups.com.

[Yordis Prieto]

Sorry wrong task

`mix format.docs`

[Norbert Melzer]

José Valim <jose....@gmail.com> schrieb am Mo., 22. Jan. 2018 um 21:07 Uhr:

My concern is that it is best if the documentation does not have the ```elixir tags, since from context, it is expected that most code is written in Elixir. The notation just adds noise. One should prefer to indent by 4 spaces.

In my opinion, codeblocks by indentation should be removed from the MD spec at all, they are not unambigous.

Sometimes I want to have distinct code blocks next to each other because they show different ways of implementing the same:

    def foo, do: 1

    def foo do

      1

    end

With indention based code blocks one can't tell if those blocks are meant to belong together or not, but with codefences this is easy:

```ex

def foo, do: 1

```

```ex

def foo do

  1

end

```

Not only I can clearly mark beginning and end of each codeblock, I get a(n optional) language annotation for free.

Of course, we do not need that annotation in elixirs documentation, as it will probably not contain (or at least very rarely contain) non exlir code. But if it does, its annotated and even better, it can be highlighted appropriately as soon as the necessary tools are available, just thinking about :makeup here…

We could even embed meta comments in those fences, eg.: ```iex nodoctest

This way we could provide consistent examples, that all look like they were straight from an iex session, but wouldn't have failing doctests because of missing context.

Plenty of options, just by using fences…

I do accept though, if you do not consider any of those for the future of elixir.

 

On the other hand, formatting of the code indented by four spaces requires partial implementation of a markdown processor and that sounds a bit outside of the scope of the formatter.

José Valim

www.plataformatec.com.br

Founder and 

Director of R&D

On Mon, Jan 22, 2018 at 8:17 PM, Yordis Prieto <yordis...@gmail.com> wrote:

It would be nice if `mix format` could take into consideration the comments as well.

Would parse for 

```elixir

```

and then extract the code and format it

What do you think about it

--
You received this message because you are subscribed to the Google Groups "elixir-lang-core" group.

To unsubscribe from this group and stop receiving emails from it, send an email to elixir-lang-co...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/elixir-lang-core/a93b4c72-d749-479e-8fd0-48560f306615%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

--
You received this message because you are subscribed to the Google Groups "elixir-lang-core" group.

To unsubscribe from this group and stop receiving emails from it, send an email to elixir-lang-co...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/elixir-lang-core/CAGnRm4LuSihA%3DNT43q5PVC2FBU7dH73tkDFNYPNsRbAGgEGYpA%40mail.gmail.com.

[Yordis Prieto]

For me I see this way,

Add an extra boilderplate code that do not kills anyone vs adding complexity that do not scale (for example adding support to other languages syntax highlights on the future, really handy for Phoenix examples where people could show Javascript code, or also NIF where people could explain C code)

I would push for use the syntax from Markdown, it is a concern less that you need to worry about it.


Anyway, so it makes sense to add it Jose if we push for markdown documentation (meaning no tabs)

You received this message because you are subscribed to a topic in the Google Groups "elixir-lang-core" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/elixir-lang-core/Y86jj5X3zhc/unsubscribe.
To unsubscribe from this group and all its topics, send an email to elixir-lang-co...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/elixir-lang-core/CA%2BbCVsuyFwi5tOK9W3m7Ntxo_YbArrT2YTNm-EpWwCVYUdY8-Q%40mail.gmail.com.

For more options, visit https://groups.google.com/d/optout.

--

Yordis Prieto Lazo

Founder & CTO, Straw Hat, LLC

Phone: +1 (786) 238-4672

[Xavier Noria]

On Mon, 22 Jan 2018 at 23:21, Norbert Melzer <timm...@gmail.com> wrote:

In my opinion, codeblocks by indentation should be removed from the MD spec at all, they are not unambigous.

Sometimes I want to have distinct code blocks next to each other because they show different ways of implementing the same:

    def foo, do: 1

    def foo do

      1

    end

With indention based code blocks one can't tell if those blocks are meant to belong together or not, but with codefences this is easy:

```ex

def foo, do: 1

```

```ex

def foo do

  1

end

```

I use indented code blocks often because the plain text version of the document flows way better for my taste. It reads like in traditional programming books where the page visually consists of chunks of English interleaved with indented listings in fixed-width font. Also, I don't value syntax highlighting as much as to sacrifice this visual flow.

Since "paragraph" is a concept that belongs to natural languages, the Markdown formatters that I've used understand that blank lines between code blocks are no paragraph separators. In practice they do what you'd expect. Even more, the original syntax spec covers this case in

    https://web.archive.org/web/20040402183259/http://daringfireball.net:80/projects/markdown/syntax#precode

so that is not by chance. CommonMark has also the same rule here http://spec.commonmark.org/0.27/#example-81.

[Yordis Prieto]

Jose,

Any updates on this one?

Specially I would love to know your opinion about markdown syntax for code

On Monday, January 22, 2018 at 11:17:57 AM UTC-8, Yordis Prieto wrote:

[José Valim]

My concern is the same.

We can only format if the ```elixir syntax is used and I personally find it a more verbose style. Similarly, doctests would also require special handling, since they use iex>.

Since this feature would be quite complex and limited to certain use cases, I do not think it is worth it to add it to Elixir itself.

José Valim

www.plataformatec.com.br

Founder and 

Director of R&D

--

You received this message because you are subscribed to the Google Groups "elixir-lang-core" group.

To unsubscribe from this group and stop receiving emails from it, send an email to elixir-lang-core+unsubscribe@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/elixir-lang-core/ed43e151-c2ef-47e6-92fe-962e1ea9c2ee%40googlegroups.com.

[Joao Pedro Evangelista]

I would say that there is value in this idea, the problem are the ones pointed by José due to backwards compat and the need to change strategies in many components on the stdlib, but it would really nice as a stand alone library to format codes embedded denoted by the ```elixir mark. It could format those blocks and hookup the task for formatting the file in a single command or a command with an option.

[Yordis Prieto]

What about that suggestion Jose?

Just format the code that uses ```elixir , it is a trade off.

[José Valim]

I am not a big fan because I don't like using ```elixir in our docs as it just pollutes the docs.

José Valim

www.plataformatec.com.br

Founder and 

Director of R&D

--

You received this message because you are subscribed to the Google Groups "elixir-lang-core" group.
To unsubscribe from this group and stop receiving emails from it, send an email to elixir-lang-core+unsubscribe@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/elixir-lang-core/9291e902-dc09-4c93-8eb0-a70716ab22b2%40googlegroups.com.