flac dev - Mar 2025 - [RFC][PATCH] API documentation: replace modules.html by topics.html

From: Michael Opdenacker <michael.opdenacker at rootcommit.com>

I'm trying to apply the change suggested on
https://lists.xiph.org/pipermail/flac-dev/2025-February/006698.html

The main idea is to replace "modules.html" by "topics.html".
However, with this change, I always get

index.html: A good starting point for learning the API is to browse through the
<a href="index.html">modules</a>.

This file refers to itself instead of pointing to topics.html as I
believe it should.

Any idea why "topics.html" is turned to "index.html" when
the documentation is generated?

Signed-off-by: Michael Opdenacker <michael.opdenacker at rootcommit.com>
Suggested-by: Christian Weisgerber <naddy at mips.inka.de>
---
 configure.ac       | 2 +-
 include/FLAC/all.h | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/configure.ac b/configure.ac
index 8eb82320..c550089c 100644
--- a/configure.ac
+++ b/configure.ac
@@ -296,7 +296,7 @@ if test "x$enable_doxygen_docs" != xfalse ; then
 fi
 AM_CONDITIONAL(FLaC__HAS_DOXYGEN, test -n "$DOXYGEN")
 
-if test ! -n "$DOXYGEN" && test -f
"$srcdir/doc/FLAC.tag" && test -f
"$srcdir/doc/api/modules.html" ; then
+if test ! -n "$DOXYGEN" && test -f
"$srcdir/doc/FLAC.tag" && test -f
"$srcdir/doc/api/index.html" ; then
 	HAS_PREBUILT_DOXYGEN=yes
 fi
 AM_CONDITIONAL(FLaC__HAS_PREBUILT_DOXYGEN, test
"x$HAS_PREBUILT_DOXYGEN" = xyes)
diff --git a/include/FLAC/all.h b/include/FLAC/all.h
index f29aa010..0be26fd7 100644
--- a/include/FLAC/all.h
+++ b/include/FLAC/all.h
@@ -102,7 +102,7 @@
  * \section getting_started Getting Started
  *
  * A good starting point for learning the API is to browse through
- * the <A HREF="modules.html">modules</A>.  Modules are
logical
+ * the <A HREF="topics.html">modules</A>.  Modules are
logical
  * groupings of related functions or classes, which correspond roughly
  * to header files or sections of header files.  Each module includes a
  * detailed description of the general usage of its functions or

Hi,

Would it be possible to provide this patch as a Github PR?

Op zo 16 mrt 2025 om 18:16 schreef <michael.opdenacker at
rootcommit.com>:
>
> From: Michael Opdenacker <michael.opdenacker at rootcommit.com>
>
> I'm trying to apply the change suggested on
> https://lists.xiph.org/pipermail/flac-dev/2025-February/006698.html
>
> The main idea is to replace "modules.html" by
"topics.html".
> However, with this change, I always get
>
> index.html: A good starting point for learning the API is to browse through
the <a href="index.html">modules</a>.
>
> This file refers to itself instead of pointing to topics.html as I
> believe it should.
>
> Any idea why "topics.html" is turned to "index.html"
when
> the documentation is generated?
>
> Signed-off-by: Michael Opdenacker <michael.opdenacker at
rootcommit.com>
> Suggested-by: Christian Weisgerber <naddy at mips.inka.de>
> ---
>  configure.ac       | 2 +-
>  include/FLAC/all.h | 2 +-
>  2 files changed, 2 insertions(+), 2 deletions(-)
>
> diff --git a/configure.ac b/configure.ac
> index 8eb82320..c550089c 100644
> --- a/configure.ac
> +++ b/configure.ac
> @@ -296,7 +296,7 @@ if test "x$enable_doxygen_docs" != xfalse ;
then
>  fi
>  AM_CONDITIONAL(FLaC__HAS_DOXYGEN, test -n "$DOXYGEN")
>
> -if test ! -n "$DOXYGEN" && test -f
"$srcdir/doc/FLAC.tag" && test -f
"$srcdir/doc/api/modules.html" ; then
> +if test ! -n "$DOXYGEN" && test -f
"$srcdir/doc/FLAC.tag" && test -f
"$srcdir/doc/api/index.html" ; then
>         HAS_PREBUILT_DOXYGEN=yes
>  fi
>  AM_CONDITIONAL(FLaC__HAS_PREBUILT_DOXYGEN, test
"x$HAS_PREBUILT_DOXYGEN" = xyes)
> diff --git a/include/FLAC/all.h b/include/FLAC/all.h
> index f29aa010..0be26fd7 100644
> --- a/include/FLAC/all.h
> +++ b/include/FLAC/all.h
> @@ -102,7 +102,7 @@
>   * \section getting_started Getting Started
>   *
>   * A good starting point for learning the API is to browse through
> - * the <A HREF="modules.html">modules</A>.  Modules
are logical
> + * the <A HREF="topics.html">modules</A>.  Modules
are logical
>   * groupings of related functions or classes, which correspond roughly
>   * to header files or sections of header files.  Each module includes a
>   * detailed description of the general usage of its functions or
> _______________________________________________
> flac-dev mailing list
> flac-dev at xiph.org
> http://lists.xiph.org/mailman/listinfo/flac-dev