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) On Mon, Jan 22, 2018 at 2:21 PM Norbert Melzer <timmel...@gmail.com> wrote: > José Valim <jose.va...@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é Valimwww.plataformatec.com.br >> <http://www.plataformatec.com.br/>Founder and Director of R&D* >> >> On Mon, Jan 22, 2018 at 8:17 PM, Yordis Prieto <yordis.pri...@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-core+unsubscr...@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 >>> <https://groups.google.com/d/msgid/elixir-lang-core/a93b4c72-d749-479e-8fd0-48560f306615%40googlegroups.com?utm_medium=email&utm_source=footer> >>> . >>> 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-core+unsubscr...@googlegroups.com. >> To view this discussion on the web visit >> https://groups.google.com/d/msgid/elixir-lang-core/CAGnRm4LuSihA%3DNT43q5PVC2FBU7dH73tkDFNYPNsRbAGgEGYpA%40mail.gmail.com >> <https://groups.google.com/d/msgid/elixir-lang-core/CAGnRm4LuSihA%3DNT43q5PVC2FBU7dH73tkDFNYPNsRbAGgEGYpA%40mail.gmail.com?utm_medium=email&utm_source=footer> >> . >> For more options, visit https://groups.google.com/d/optout. >> > -- > 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-core+unsubscr...@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 > <https://groups.google.com/d/msgid/elixir-lang-core/CA%2BbCVsuyFwi5tOK9W3m7Ntxo_YbArrT2YTNm-EpWwCVYUdY8-Q%40mail.gmail.com?utm_medium=email&utm_source=footer> > . > For more options, visit https://groups.google.com/d/optout. > -- Yordis Prieto Lazo Founder & CTO, Straw Hat, LLC Phone: +1 (786) 238-4672 -- 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+unsubscr...@googlegroups.com. To view this discussion on the web visit https://groups.google.com/d/msgid/elixir-lang-core/CAAKqwiGa-0Fp3sig0pJ%2Bv5-BJ872_2EOYOy2O%3DXjsmSsrj1LGw%40mail.gmail.com. For more options, visit https://groups.google.com/d/optout.
