MPR#7548 Add an example of using the printf function to the manual

[Lereena]

Added a description and examples of using the printf function to the manual section "1.8 Pretty-printing", closing the MPR#7548.

[gasche]

Thanks for the patch proposal! The content that you propose is very nice, and it will be a good addition to the tutorial.

I think that you could have a new section to introduce Printf (for example named "Printf formats"), instead of being at the end of the "Pretty-printing" section.

The original intent of the mantis ticket you reference was to include a version of the full pretty-printer using Printf. This probably requires the use of the more advanced format specifier %a (and changing the function to take a out_channel as argument for this to work):

let print ppf expr =
  ...
  let rec print prec ppf expr =
     ...
      | Quot(f, g) ->
          open_paren prec 2 ppf;
          Printf.fprintf ppf "%a / %a" (print 2) f (print 3) g;
          close_paren prec 2 ppf

This could go at the end of the new content you wrote ("Here is how to rewrite the pretty-printer using Printf.fprintf"), probably after having introduced fprintf before --- like printf, but parametrized on the output channel. But this does not need to be part of the present Pull Request: with a separate section name, I think this is good to merge even if we don't have a port of the full pretty-printer.

(Of course the feedback of @mseri is also excellent -- but on the last point, I think the pretty-printer could wait for another PR.)

[mseri]

@gasche I fully agree that the pretty-printer example could be added in a second stage, and I quite like the idea of having this moved earlier on (and focusing on the easier Printf more than on Format).

[Octachron]

Thanks for the contribution! I have some remarks in term of contents and emphases but this is a good start.

[gasche]

@Lereena: when you have time, it would be nice if you could integrate the feedback you got from the various commenters into the PR (by adding more commits or amending your commit, and pushing to the remote branch again).

Some of the comments are a bit open-ended, and it's fine if some things are left for later, but at least easy/local change suggestions that you agree would improve the result should be handled. For the rest, you should do as you think is best to get a next iteration.

[Lereena]

@gasche @mseri @Octachron Thank you very much for feedback, I will make corrections tomorrow

[mseri]

Nice, you also added the pretty printer example! Thanks, this is a great addition to the examples

[Lereena]

I corrected the wording and function calls, added links and a printer. I didn’t write about the Format module, in my opinion this is so far superfluous

[gasche]

I made a couple minor comments but this looks almost ready for merging. Thanks!

[Lereena]

@gasche I fixed wording and used an example that you proposed, thank you very much.

[Lereena]

I am very sorry and extremely embarrassed that my contribution is so long and takes a lot of your attention D: Thank you for helping.

[Octachron]

@Lereena , you should not feel embarrassed: it is perfectly normal to have a lot of back-and-forth between the author and editors(or reviewers) before reaching the "right" text. Clarity and simplicity sometimes requires a lot of work, and this PR is on the right track.

[Drup]

I like the idea of introducing printf in the tutorial! :)

I would suggest using pp_* as a prefix. pp is the standard name for pretty printers, and there is already a set of output_* function in Pervasive which do something quite different.

I'm also of the opinion we should advertise Format directly. Especially since in this case, the code is strictly identical. Although I understand that not everyone agrees on that.

[Lereena]

I would suggest using pp_* as a prefix. pp is the standard name for pretty printers, and there is already a set of output_* function in Pervasive which do something quite different.

I agree, there can really be a misunderstanding. Made a change

[Armael]

A couple of minor remarks.

[Octachron]

I have done one more round of review. The new section shaping up nicely and it should be good to go after that round.

[Octachron]

We are near here! I have two small remaining remarks:

[Octachron]

I like the last version. I will merge it once CI passes. Thanks for your patience!