Documentation: how to use the pretty printing functions

[lindig]

I struggle to understand from the documentation in the MLI how to format a timestamp using a format string that uses %Y and so on. Why are there so many pp functions defined? It would appear that you just need one that understands all the format specifiers. A small example how to create a string that contains a date according to (say) %Y%M%D would go a long way.

[c-cube]

looking at the doc I came up with this:

# let time = Unix.gettimeofday() in
Format.printf "%a@."
  (fun oc f->ISO8601.Permissive.(pp_format oc "%Y/%M/%D at %h:%m:%s" f 0.)) 
  time;;
2020/12/08 at 15:37:13 TZ 00

I think the signature is inconvenient because it doesn't lend itself well to %a.

[lindig]

Indeed. It's probably more complicated than typical pretty printers because those don't create their own format specifiers and have just one way of formatting an abstract value.

[c-cube]

Generally speaking, I think the value of this library is in the printers for the ISO8601 format, which are the other named printers. I didn't even pay attention to pp_format before :slightly_smiling_face:

[lindig]

Maybe the many pp functions are there for this reason: pp_date would insert the date based on %Y-%M-%D for %a such that for common cases you can avoid the complications laid out above. If so, this would be worth spelling out in the MLI file.