From 571345841ae4a307bb50b909567c9fc58e648db2 Mon Sep 17 00:00:00 2001 From: github-actions Date: Sun, 22 Sep 2024 11:43:39 +0000 Subject: [PATCH] [automated site update] --- apidoc/html/index.html | 19 ++++++++++++++++- apidoc/html/navtreedata.js | 9 ++++---- apidoc/html/navtreeindex0.js | 40 ++++++++++++++++++------------------ apidoc/html/navtreeindex1.js | 4 ++-- apidoc/html/navtreeindex2.js | 4 ++-- apidoc/html/navtreeindex3.js | 1 + apidoc/html/search/all_14.js | 5 +++-- apidoc/html/search/all_15.js | 9 ++++---- apidoc/html/search/all_7.js | 29 +++++++++++++------------- apidoc/html/toc.xml | 3 ++- apidoc/supernovas.tag | 1 + doc/README.md | 22 ++++++++++++++++++++ 12 files changed, 96 insertions(+), 50 deletions(-) diff --git a/apidoc/html/index.html b/apidoc/html/index.html index 47696107..d0d4055a 100644 --- a/apidoc/html/index.html +++ b/apidoc/html/index.html @@ -133,6 +133,7 @@

  • Notes on precision
  • SuperNOVAS specific features
  • External Solar-system ephemeris data or services
    • +
  • Runtime Debug support
  • Release schedule
    • @@ -599,8 +600,24 @@

    For Solar-system objects other than the major planets, you may also provide your own readeph() implementation. (In this case you will want to set DEFAULT_READEPH in config.mk to specify your source code for that function before building the SuperNOVAS library, or else disable that option entirely (e.g. by commenting or removing it), and link your application explicitly with your readeph() implementation.

    The downside of this approach is that your SuperNOVAS library will not be usable without invariably providing a solarsystem() / solarsystem_hp() and/or readeph() implementations for every application that you will want to use SuperNOVAS with. This is why the runtime configuration of the ephemeris provider functions is the best and most generic way to add your preferred implementations while also providing some minimum default implementations for other users of the library, who may not need your ephemeris service, or have no need for planet data beyond the approximate positions for the Earth and Sun.

    -

    +

    +Runtime debug support

    +

    You can enable or disable debugging output to stderr with novas_debug(enum novas_debug_mode), where the argument is one of the defined constants from novas.h:

    + + + + + + + + + +
    novas_debug_mode value Description
    NOVAS_DEBUG_OFF No debugging output (default)
    NOVAS_DEBUG_ON Prints error messages and traces to stderr
    NOVAS_DEBUG_EXTRA Same as above but with stricter error checking
    +

    The main difference between NOVAS_DEBUG_ON and NOVAS_DEBUG_EXTRA is that the latter will treat minor issues as errors also, while the former may ignore them. For example, place() will return normally by default if it cannot calculate gravitational bending around massive planets in full accuracy mode. It is unlikely that this omission would significantly alter the result in most cases, except for some very specific ones when observing in a direction close to a major planet. Thus, with NOVAS_DEBUG_ON, place() go about as usual even if the Jupiter's position is not known. However, NOVAS_DEBUG_EXTRA will not give it a free pass, and will make place() return an error (and print the trace) if it cannot properly account for gravitational bending around the major planets as it is expected to.

    +
    +

    +

    Release schedule

    A predictable release schedule and process can help manage expectations and reduce stress on adopters and developers alike.

    Releases of the library shall follow a quarterly release schedule. You may expect upcoming releases to be published around February 1, May 1, August 1, and/or November 1 each year, on an as-needed basis. That means that if there are outstanding bugs, or new pull requests (PRs), you may expect a release that addresses these in the upcoming quarter. The dates are placeholders only, with no guarantee that a new release will actually be available every quarter. If nothing of note comes up, a potential release date may pass without a release being published.

    diff --git a/apidoc/html/navtreedata.js b/apidoc/html/navtreedata.js index e984b378..f7b0d8b9 100644 --- a/apidoc/html/navtreedata.js +++ b/apidoc/html/navtreedata.js @@ -67,7 +67,8 @@ var NAVTREE = ] ], [ "3. Explicit linking of custom ephemeris functions", "index.html#autotoc_md67", null ] ] ], - [ "Release schedule", "index.html#autotoc_md69", null ], + [ "Runtime debug support", "index.html#autotoc_md69", null ], + [ "Release schedule", "index.html#autotoc_md71", null ], [ "[Unreleased]", "md_CHANGELOG.html#autotoc_md1", [ [ "Fixed", "md_CHANGELOG.html#autotoc_md2", null ], [ "Changed", "md_CHANGELOG.html#autotoc_md3", null ] @@ -130,9 +131,9 @@ var NAVTREE = var NAVTREEINDEX = [ "annotated.html", -"novas_8c.html#aead87744eeb3029ce7d5ffb1801ee652", -"novas_8h.html#ace5e59ce1564bf6c61946c290bb05367a84da44f7510d8c99353b1b1c6bb4faf8", -"super_8c.html#ae68d01655c4b37b5a3e1422f0062f94c" +"novas_8c.html#aea0e1028baf14d16d9de800e36a17086", +"novas_8h.html#ace5e59ce1564bf6c61946c290bb05367a6833dbc8bfb3b8ba2cdd7a2da0b82353", +"super_8c.html#adb48b2acaf76cc3a1e3a1412cc42c232" ]; var SYNCONMSG = 'click to disable panel synchronisation'; diff --git a/apidoc/html/navtreeindex0.js b/apidoc/html/navtreeindex0.js index de6f4316..3e0ba99f 100644 --- a/apidoc/html/navtreeindex0.js +++ b/apidoc/html/navtreeindex0.js @@ -46,8 +46,8 @@ var NAVTREEINDEX0 = "frames_8c.html#ae84debf8ab4d3b16feaaefdcb0ebbd08":[5,0,1,1,4], "functions.html":[4,2,0], "functions_vars.html":[4,2,1], -"globals.html":[5,1,0,0], "globals.html":[5,1,0], +"globals.html":[5,1,0,0], "globals_b.html":[5,1,0,1], "globals_c.html":[5,1,0,2], "globals_d.html":[5,1,0,3], @@ -56,8 +56,8 @@ var NAVTREEINDEX0 = "globals_enum.html":[5,1,4], "globals_eval.html":[5,1,5], "globals_f.html":[5,1,0,5], -"globals_func.html":[5,1,1], "globals_func.html":[5,1,1,0], +"globals_func.html":[5,1,1], "globals_func_b.html":[5,1,1,1], "globals_func_c.html":[5,1,1,2], "globals_func_d.html":[5,1,1,3], @@ -129,23 +129,24 @@ var NAVTREEINDEX0 = "index.html#autotoc_md66":[8,1,1], "index.html#autotoc_md67":[8,2], "index.html#autotoc_md69":[9], +"index.html#autotoc_md71":[10], "md_CHANGELOG.html":[0], -"md_CHANGELOG.html#autotoc_md1":[0,10], -"md_CHANGELOG.html#autotoc_md10":[0,12,1], -"md_CHANGELOG.html#autotoc_md11":[0,12,2], -"md_CHANGELOG.html#autotoc_md12":[0,13], -"md_CHANGELOG.html#autotoc_md13":[0,13,0], -"md_CHANGELOG.html#autotoc_md14":[0,13,1], -"md_CHANGELOG.html#autotoc_md15":[0,13,2], -"md_CHANGELOG.html#autotoc_md16":[0,13,3], -"md_CHANGELOG.html#autotoc_md2":[0,10,0], -"md_CHANGELOG.html#autotoc_md3":[0,10,1], -"md_CHANGELOG.html#autotoc_md4":[0,11], -"md_CHANGELOG.html#autotoc_md5":[0,11,0], -"md_CHANGELOG.html#autotoc_md6":[0,11,1], -"md_CHANGELOG.html#autotoc_md7":[0,11,2], -"md_CHANGELOG.html#autotoc_md8":[0,12], -"md_CHANGELOG.html#autotoc_md9":[0,12,0], +"md_CHANGELOG.html#autotoc_md1":[0,11], +"md_CHANGELOG.html#autotoc_md10":[0,13,1], +"md_CHANGELOG.html#autotoc_md11":[0,13,2], +"md_CHANGELOG.html#autotoc_md12":[0,14], +"md_CHANGELOG.html#autotoc_md13":[0,14,0], +"md_CHANGELOG.html#autotoc_md14":[0,14,1], +"md_CHANGELOG.html#autotoc_md15":[0,14,2], +"md_CHANGELOG.html#autotoc_md16":[0,14,3], +"md_CHANGELOG.html#autotoc_md2":[0,11,0], +"md_CHANGELOG.html#autotoc_md3":[0,11,1], +"md_CHANGELOG.html#autotoc_md4":[0,12], +"md_CHANGELOG.html#autotoc_md5":[0,12,0], +"md_CHANGELOG.html#autotoc_md6":[0,12,1], +"md_CHANGELOG.html#autotoc_md7":[0,12,2], +"md_CHANGELOG.html#autotoc_md8":[0,13], +"md_CHANGELOG.html#autotoc_md9":[0,13,0], "md_CONTRIBUTING.html":[1], "md_LEGACY.html":[2], "md_LEGACY.html#autotoc_md19":[2,0], @@ -248,6 +249,5 @@ var NAVTREEINDEX0 = "novas_8c.html#ad2b933ce2f58e8b04bbe76ffbff99eb0":[5,0,1,2,98], "novas_8c.html#ad799864f637c483fb49491bde5a93e25":[5,0,1,2,15], "novas_8c.html#add7a260017fad0d59c943a0a8d935fcf":[5,0,1,2,18], -"novas_8c.html#ade8207981b6f840d1f0a79dd0c72beb2":[5,0,1,2,66], -"novas_8c.html#aea0e1028baf14d16d9de800e36a17086":[5,0,1,2,35] +"novas_8c.html#ade8207981b6f840d1f0a79dd0c72beb2":[5,0,1,2,66] }; diff --git a/apidoc/html/navtreeindex1.js b/apidoc/html/navtreeindex1.js index cb35adf1..1be8d98d 100644 --- a/apidoc/html/navtreeindex1.js +++ b/apidoc/html/navtreeindex1.js @@ -1,5 +1,6 @@ var NAVTREEINDEX1 = { +"novas_8c.html#aea0e1028baf14d16d9de800e36a17086":[5,0,1,2,35], "novas_8c.html#aead87744eeb3029ce7d5ffb1801ee652":[5,0,1,2,94], "novas_8c.html#aed179ad664f4ff023deb540140f3c2ef":[5,0,1,2,71], "novas_8c.html#aeea4b5085c7267714492fae6108fb975":[5,0,1,2,29], @@ -248,6 +249,5 @@ var NAVTREEINDEX1 = "novas_8h.html#acd47f30801a6676afb5e0614eaefa569":[5,0,0,0,228], "novas_8h.html#ace5e59ce1564bf6c61946c290bb05367":[5,0,0,0,84], "novas_8h.html#ace5e59ce1564bf6c61946c290bb05367a197e40a273d8132592b60efe3f87a065":[5,0,0,0,84,0], -"novas_8h.html#ace5e59ce1564bf6c61946c290bb05367a1b1e38f90bc3bc3c9f1c04aa2c959444":[5,0,0,0,84,4], -"novas_8h.html#ace5e59ce1564bf6c61946c290bb05367a6833dbc8bfb3b8ba2cdd7a2da0b82353":[5,0,0,0,84,1] +"novas_8h.html#ace5e59ce1564bf6c61946c290bb05367a1b1e38f90bc3bc3c9f1c04aa2c959444":[5,0,0,0,84,4] }; diff --git a/apidoc/html/navtreeindex2.js b/apidoc/html/navtreeindex2.js index 440d8686..c5c732a7 100644 --- a/apidoc/html/navtreeindex2.js +++ b/apidoc/html/navtreeindex2.js @@ -1,5 +1,6 @@ var NAVTREEINDEX2 = { +"novas_8h.html#ace5e59ce1564bf6c61946c290bb05367a6833dbc8bfb3b8ba2cdd7a2da0b82353":[5,0,0,0,84,1], "novas_8h.html#ace5e59ce1564bf6c61946c290bb05367a84da44f7510d8c99353b1b1c6bb4faf8":[5,0,0,0,84,3], "novas_8h.html#ace5e59ce1564bf6c61946c290bb05367a882f5d97444df44485d360ce298843b1":[5,0,0,0,84,2], "novas_8h.html#acf86ce700b3d3509ebba13e5f16a4327":[5,0,0,0,205], @@ -248,6 +249,5 @@ var NAVTREEINDEX2 = "super_8c.html#ab7611704bab9ce717744a8b5575c5378":[5,0,1,10,7], "super_8c.html#ab9b7a622486f2904615ceed1ba94cd8f":[5,0,1,10,16], "super_8c.html#acbcd90c9111cc5580a5c2bac404f7f00":[5,0,1,10,20], -"super_8c.html#ad290005b13558de3927e455775b32e0f":[5,0,1,10,10], -"super_8c.html#adb48b2acaf76cc3a1e3a1412cc42c232":[5,0,1,10,25] +"super_8c.html#ad290005b13558de3927e455775b32e0f":[5,0,1,10,10] }; diff --git a/apidoc/html/navtreeindex3.js b/apidoc/html/navtreeindex3.js index 306034dc..931cf365 100644 --- a/apidoc/html/navtreeindex3.js +++ b/apidoc/html/navtreeindex3.js @@ -1,5 +1,6 @@ var NAVTREEINDEX3 = { +"super_8c.html#adb48b2acaf76cc3a1e3a1412cc42c232":[5,0,1,10,25], "super_8c.html#ae68d01655c4b37b5a3e1422f0062f94c":[5,0,1,10,9], "super_8c.html#aebad3c9b51f62cb7b31a686b5ec890a9":[5,0,1,10,19], "super_8c.html#af4cce5aa6c74794a0b89176037305181":[5,0,1,10,5], diff --git a/apidoc/html/search/all_14.js b/apidoc/html/search/all_14.js index 225a6309..803600a1 100644 --- a/apidoc/html/search/all_14.js +++ b/apidoc/html/search/all_14.js @@ -21,8 +21,9 @@ var searchData= ['refract_5fastro_18',['refract_astro',['../novas_8h.html#a46d245f56c6eea9b1a7dc32d3feeaeb8',1,'refract_astro(const on_surface *location, enum novas_refraction_model option, double zd_calc): novas.c'],['../novas_8c.html#aa41408d8cbbe3cfc12930414a9c79fc7',1,'refract_astro(const on_surface *location, enum novas_refraction_model option, double zd_astro): novas.c']]], ['refractionmodel_19',['RefractionModel',['../novas_8h.html#ad4899a6116cfbbe17400e7ef0c8426a9',1,'novas.h']]], ['related_20links_20',['Related links',['../index.html#autotoc_md31',1,'']]], - ['release_20schedule_21',['Release schedule',['../index.html#autotoc_md69',1,'']]], + ['release_20schedule_21',['Release schedule',['../index.html#autotoc_md71',1,'']]], ['results_22',['Prerequisites to precise results',['../index.html#autotoc_md55',1,'']]], ['rmass_23',['rmass',['../novascon_8c.html#a19a7c107c3918c90c90cdad5ab310b1a',1,'RMASS: novascon.c'],['../novascon_8h.html#a19a7c107c3918c90c90cdad5ab310b1a',1,'RMASS: novascon.c']]], - ['rv_24',['rv',['../structsky__pos.html#ad9e8b5daff39072d109a6f4f1fa61f55',1,'sky_pos']]] + ['runtime_20debug_20support_24',['Runtime debug support',['../index.html#autotoc_md69',1,'']]], + ['rv_25',['rv',['../structsky__pos.html#ad9e8b5daff39072d109a6f4f1fa61f55',1,'sky_pos']]] ]; diff --git a/apidoc/html/search/all_15.js b/apidoc/html/search/all_15.js index f403574f..b06d09bd 100644 --- a/apidoc/html/search/all_15.js +++ b/apidoc/html/search/all_15.js @@ -3,7 +3,7 @@ var searchData= ['s_20tt_20pleph_20tt_20fortran_20interface_0',['2.b. Planets via JPL's <tt>pleph</tt> FORTRAN interface',['../index.html#autotoc_md66',1,'']]], ['sc_5fpos_1',['sc_pos',['../structin__space.html#abc3736b39d63bfabf73a25e3b03b91d8',1,'in_space']]], ['sc_5fvel_2',['sc_vel',['../structin__space.html#a9615dabeef0c31f47546c8083b768257',1,'in_space']]], - ['schedule_3',['Release schedule',['../index.html#autotoc_md69',1,'']]], + ['schedule_3',['Release schedule',['../index.html#autotoc_md71',1,'']]], ['service_20integration_4',['1. Universal ephemeris data / service integration',['../index.html#autotoc_md63',1,'']]], ['services_5',['External Solar-system ephemeris data or services',['../index.html#autotoc_md62',1,'']]], ['set_20up_20the_20observing_20frame_6',['Set up the observing frame',['../index.html#autotoc_md46',1,'']]], @@ -54,7 +54,8 @@ var searchData= ['supernovas_5fpatchlevel_51',['SUPERNOVAS_PATCHLEVEL',['../novas_8h.html#a9b926427954233b94ebd6925d86f9f81',1,'novas.h']]], ['supernovas_5frelease_5fstring_52',['SUPERNOVAS_RELEASE_STRING',['../novas_8h.html#aadef42ba39811e058ee9efe2c6f7d151',1,'novas.h']]], ['supernovas_5fversion_5fstring_53',['SUPERNOVAS_VERSION_STRING',['../novas_8h.html#a44de9d1672290d153a1dfb0685886208',1,'novas.h']]], - ['support_20for_20old_20jpl_20major_20planet_20ephemerides_54',['2. Built-in support for (old) JPL major planet ephemerides',['../index.html#autotoc_md64',1,'']]], - ['system_20ephemeris_20data_20or_20services_55',['External Solar-system ephemeris data or services',['../index.html#autotoc_md62',1,'']]], - ['system_20source_56',['system source',['../md_LEGACY.html#autotoc_md27',1,'Calculating positions for a Solar-system source'],['../index.html#autotoc_md49',1,'Calculating positions for a Solar-system source']]] + ['support_54',['Runtime debug support',['../index.html#autotoc_md69',1,'']]], + ['support_20for_20old_20jpl_20major_20planet_20ephemerides_55',['2. Built-in support for (old) JPL major planet ephemerides',['../index.html#autotoc_md64',1,'']]], + ['system_20ephemeris_20data_20or_20services_56',['External Solar-system ephemeris data or services',['../index.html#autotoc_md62',1,'']]], + ['system_20source_57',['system source',['../md_LEGACY.html#autotoc_md27',1,'Calculating positions for a Solar-system source'],['../index.html#autotoc_md49',1,'Calculating positions for a Solar-system source']]] ]; diff --git a/apidoc/html/search/all_7.js b/apidoc/html/search/all_7.js index 6a6e816a..90ee51b5 100644 --- a/apidoc/html/search/all_7.js +++ b/apidoc/html/search/all_7.js @@ -6,18 +6,19 @@ var searchData= ['data_20or_20services_3',['External Solar-system ephemeris data or services',['../index.html#autotoc_md62',1,'']]], ['data_20service_20integration_4',['1. Universal ephemeris data / service integration',['../index.html#autotoc_md63',1,'']]], ['de405_5fau_5',['DE405_AU',['../novas_8h.html#af303bf91582509624aa40c6a87eb95ac',1,'novas.h']]], - ['dec_6',['dec',['../structsky__pos.html#ac4ae7989694321b540abb75c30eec690',1,'sky_pos::dec'],['../structcat__entry.html#ac4ae7989694321b540abb75c30eec690',1,'cat_entry::dec']]], - ['declination_7',['A. True apparent R.A. and declination',['../md_LEGACY.html#autotoc_md25',1,'']]], - ['default_5fcio_5flocator_5ffile_8',['DEFAULT_CIO_LOCATOR_FILE',['../novas_8h.html#a4caf1f6e33a208827eb99df7e387d6d1',1,'novas.h']]], - ['default_5fgrav_5fbodies_5ffull_5faccuracy_9',['DEFAULT_GRAV_BODIES_FULL_ACCURACY',['../novas_8h.html#a4cb74da554b236c835302480688cfaac',1,'novas.h']]], - ['default_5fgrav_5fbodies_5freduced_5faccuracy_10',['DEFAULT_GRAV_BODIES_REDUCED_ACCURACY',['../novas_8h.html#aec64bf67d5a03b2b4fb2583e5918f1de',1,'novas.h']]], - ['deg2rad_11',['DEG2RAD',['../novas_8h.html#af7e8592d0a634bd3642e9fd508ea8022',1,'novas.h']]], - ['deprecated_12',['Deprecated',['../md_CHANGELOG.html#autotoc_md16',1,'']]], - ['deprecated_20list_13',['Deprecated List',['../deprecated.html',1,'']]], - ['deps0_14',['deps0',['../structnovas__frame.html#afb1bb47af5a00647759b897f72a68b58',1,'novas_frame']]], - ['dis_15',['dis',['../structsky__pos.html#aeedff25e8c80502a891e8af33d35b3c0',1,'sky_pos']]], - ['dpsi0_16',['dpsi0',['../structnovas__frame.html#a4445e3f8a201b14a5a7068c87507de72',1,'novas_frame']]], - ['dut1_17',['dut1',['../structnovas__timespec.html#a281e93817d681ec4a6cea2601a15c566',1,'novas_timespec']]], - ['dx_18',['dx',['../structnovas__frame.html#a229d11aff11a7482259d1296b9b70b8a',1,'novas_frame']]], - ['dy_19',['dy',['../structnovas__frame.html#a9deb6f886b19d50e714d890c3c268efc',1,'novas_frame']]] + ['debug_20support_6',['Runtime debug support',['../index.html#autotoc_md69',1,'']]], + ['dec_7',['dec',['../structsky__pos.html#ac4ae7989694321b540abb75c30eec690',1,'sky_pos::dec'],['../structcat__entry.html#ac4ae7989694321b540abb75c30eec690',1,'cat_entry::dec']]], + ['declination_8',['A. True apparent R.A. and declination',['../md_LEGACY.html#autotoc_md25',1,'']]], + ['default_5fcio_5flocator_5ffile_9',['DEFAULT_CIO_LOCATOR_FILE',['../novas_8h.html#a4caf1f6e33a208827eb99df7e387d6d1',1,'novas.h']]], + ['default_5fgrav_5fbodies_5ffull_5faccuracy_10',['DEFAULT_GRAV_BODIES_FULL_ACCURACY',['../novas_8h.html#a4cb74da554b236c835302480688cfaac',1,'novas.h']]], + ['default_5fgrav_5fbodies_5freduced_5faccuracy_11',['DEFAULT_GRAV_BODIES_REDUCED_ACCURACY',['../novas_8h.html#aec64bf67d5a03b2b4fb2583e5918f1de',1,'novas.h']]], + ['deg2rad_12',['DEG2RAD',['../novas_8h.html#af7e8592d0a634bd3642e9fd508ea8022',1,'novas.h']]], + ['deprecated_13',['Deprecated',['../md_CHANGELOG.html#autotoc_md16',1,'']]], + ['deprecated_20list_14',['Deprecated List',['../deprecated.html',1,'']]], + ['deps0_15',['deps0',['../structnovas__frame.html#afb1bb47af5a00647759b897f72a68b58',1,'novas_frame']]], + ['dis_16',['dis',['../structsky__pos.html#aeedff25e8c80502a891e8af33d35b3c0',1,'sky_pos']]], + ['dpsi0_17',['dpsi0',['../structnovas__frame.html#a4445e3f8a201b14a5a7068c87507de72',1,'novas_frame']]], + ['dut1_18',['dut1',['../structnovas__timespec.html#a281e93817d681ec4a6cea2601a15c566',1,'novas_timespec']]], + ['dx_19',['dx',['../structnovas__frame.html#a229d11aff11a7482259d1296b9b70b8a',1,'novas_frame']]], + ['dy_20',['dy',['../structnovas__frame.html#a9deb6f886b19d50e714d890c3c268efc',1,'novas_frame']]] ]; diff --git a/apidoc/html/toc.xml b/apidoc/html/toc.xml index 54a9d5a7..86ab5e75 100644 --- a/apidoc/html/toc.xml +++ b/apidoc/html/toc.xml @@ -39,7 +39,8 @@ - + + diff --git a/apidoc/supernovas.tag b/apidoc/supernovas.tag index 551c8da3..714239db 100644 --- a/apidoc/supernovas.tag +++ b/apidoc/supernovas.tag @@ -4438,6 +4438,7 @@ universal-ephemerides builtin-ephem-readers explicit-ephem-linking + debug-support release-schedule diff --git a/doc/README.md b/doc/README.md index 2d88b3eb..83ee9079 100644 --- a/doc/README.md +++ b/doc/README.md @@ -27,6 +27,7 @@ This document has been updated for the `v1.1` release. - [Notes on precision](#precision) - [SuperNOVAS specific features](#supernovas-features) - [External Solar-system ephemeris data or services](#solarsystem) + - [Runtime Debug support](#debug-support) - [Release schedule](#release-schedule) @@ -991,6 +992,27 @@ most generic way to add your preferred implementations while also providing some _other users_ of the library, who may not need _your_ ephemeris service, or have no need for planet data beyond the approximate positions for the Earth and Sun. +----------------------------------------------------------------------------- + + +## Runtime debug support + +You can enable or disable debugging output to `stderr` with `novas_debug(enum novas_debug_mode)`, where the argument +is one of the defined constants from `novas.h`: + + | `novas_debug_mode` value | Description | + | -------------------------- | -------------------------------------------------- | + | `NOVAS_DEBUG_OFF` | No debugging output (_default_) | + | `NOVAS_DEBUG_ON` | Prints error messages and traces to `stderr` | + | `NOVAS_DEBUG_EXTRA` | Same as above but with stricter error checking | + +The main difference between `NOVAS_DEBUG_ON` and `NOVAS_DEBUG_EXTRA` is that the latter will treat minor issues as +errors also, while the former may ignore them. For example, `place()` will return normally by default if it cannot +calculate gravitational bending around massive planets in full accuracy mode. It is unlikely that this omission would +significantly alter the result in most cases, except for some very specific ones when observing in a direction close +to a major planet. Thus, with `NOVAS_DEBUG_ON`, `place()` go about as usual even if the Jupiter's position is not +known. However, `NOVAS_DEBUG_EXTRA` will not give it a free pass, and will make `place()` return an error (and print +the trace) if it cannot properly account for gravitational bending around the major planets as it is expected to. -----------------------------------------------------------------------------