- update documentation

    * correct the part about fixed aspect
    * improve formatting
    * add snippet markers to source
    * replace inline code by @snippet
  - do not run calibration twice when using a imageList
  - make output consistent in itself (CamelCase vs no_camel_case) as well as with old camera calibrate sample
  - respect write extrinsic/ points flags
  - set the aspectRatio value when specified
  - fix writing of calibration settings. also update grammar.
  - fix intendation and remove some size_t -> int casts by using size_t