Bug#778655: doxygen: Doxygen should not enable markdown by default
Control: severity -1 important no feedback, based on Helmuts analysis, this doesn't look release critical. On 02/18/2015 08:58 PM, Helmut Grohne wrote: Control: tags -1 + moreinfo Hi Ron, Duplicating a bit of our discussion here for keeping track of it. On Wed, Feb 18, 2015 at 09:58:25AM +1030, Ron wrote: So doxygen 1.8 added support for interpreting markdown, and it does this in all normal comment blocks before applying the normal doxygen formatting. Unfortunately, they also chose to enable this by default, so any package that is building docs against this version, which didn't update the doxyconf configuration using this version, to see that this option exists and to turn it off if it breaks the generated documentation, is going to run a fairly high chance of generating fairly horribly broken docs. A quick canary for the extent of this problem is to search for: 'warning: unexpected command endcode' Which went by uncommented on (or I assume inspected) in logs such as was posted to https://bugs.debian.org/680896 and many other places. This is just one fairly common way this fails horribly, resulting in all the comments *above* a @code section being treated as code, and the code section itself being dumped literally to the output - but there are quite a few other ways this will generate awful unreadable documentation when markdown syntax is inadvertently applied to an existing codebase. Thanks for reporting this. I was not aware! Unless we want to ship with a lot of fairly useless -doc packages, it seems like this should probably be disabled by default, until people have become more aware of the problem and have taken steps to avoid it in their own source. I found a lot of build logs that show people having this problem, but no discussion of the cause, the impact, or the fix. I suspect a lot of people who build -doc packages rarely or never actually read them themselves ... Flipping the default of MARKDOWN_SUPPORT in Debian won't happen for the following reasons: * Deviating from upstream is bad. Of course, this means that convincing upstream to change the default necessitates revisiting this decision. * Changing this in the doxygen package won't fix any documentation: I don't expect many packages to be uploaded after a doxygen upload and binNMUs cannot be used as most documentation resides in arch:all packages. Thus it should be easier to just fix build-rdeps of doxygen. Fixing the ones that are already broken is probably going to be something of a major operation in its own right, but the mood in #d-d seemed to be that we should start by limiting the damage here and then tackle that part separately. And this is where the moreinfo tag comes into place: The information of which packages actually are broken is missing entirely. Before this bug becomes actionable in any way, the purported damage needs to be understood. Please remove the moreinfo tag when adding an affected jessie package and explaining how it is affected. Let me add a few hints on which packages to look for. The following packages set MARKDOWN_SUPPORT=NO: hdf5 hwloc libsbml mpich openms ppl simbody witty The following packages set MARKDOWN_SUPPORT=YES: ace apophenia apt aubio bladerf boost1.54 boost1.55 casablanca clipper cmocka colobot cpl csound cupt eigen3 elektra exiv2 feel++ fflas-ffpack freecontact gazebo gdcm geographiclib givaro glfw3 gnuradio gr-fcdproplus grass gtkspellmm imagemagick libam7xxx libburn libcaca libclaw libdatrie libdebian-installer libevdev libhmsbeagle liblo libltc libopendbx libreoffice libsdl2-gfx libsidplayfp libssh libstxxl libthai linbox litl lvtk lxc mysql-workbench ns3 ogre-1.9 openmprtl orthanc pcl psocksxx python-odf qof rapidjson rivet schroot sdformat serd simgrid sord speech-tools sratom ui-gxmlcpp ui-utilcpp v4l-utils visp vlfeat websocketpp The vast majority of build-rdeps of doxygen or doxygen-latex appear to not set MARKDOWN_SUPPORT at all. Helmut -- To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Bug#778655: doxygen: Doxygen should not enable markdown by default
Control: tags -1 + moreinfo Hi Ron, Duplicating a bit of our discussion here for keeping track of it. On Wed, Feb 18, 2015 at 09:58:25AM +1030, Ron wrote: So doxygen 1.8 added support for interpreting markdown, and it does this in all normal comment blocks before applying the normal doxygen formatting. Unfortunately, they also chose to enable this by default, so any package that is building docs against this version, which didn't update the doxyconf configuration using this version, to see that this option exists and to turn it off if it breaks the generated documentation, is going to run a fairly high chance of generating fairly horribly broken docs. A quick canary for the extent of this problem is to search for: 'warning: unexpected command endcode' Which went by uncommented on (or I assume inspected) in logs such as was posted to https://bugs.debian.org/680896 and many other places. This is just one fairly common way this fails horribly, resulting in all the comments *above* a @code section being treated as code, and the code section itself being dumped literally to the output - but there are quite a few other ways this will generate awful unreadable documentation when markdown syntax is inadvertently applied to an existing codebase. Thanks for reporting this. I was not aware! Unless we want to ship with a lot of fairly useless -doc packages, it seems like this should probably be disabled by default, until people have become more aware of the problem and have taken steps to avoid it in their own source. I found a lot of build logs that show people having this problem, but no discussion of the cause, the impact, or the fix. I suspect a lot of people who build -doc packages rarely or never actually read them themselves ... Flipping the default of MARKDOWN_SUPPORT in Debian won't happen for the following reasons: * Deviating from upstream is bad. Of course, this means that convincing upstream to change the default necessitates revisiting this decision. * Changing this in the doxygen package won't fix any documentation: I don't expect many packages to be uploaded after a doxygen upload and binNMUs cannot be used as most documentation resides in arch:all packages. Thus it should be easier to just fix build-rdeps of doxygen. Fixing the ones that are already broken is probably going to be something of a major operation in its own right, but the mood in #d-d seemed to be that we should start by limiting the damage here and then tackle that part separately. And this is where the moreinfo tag comes into place: The information of which packages actually are broken is missing entirely. Before this bug becomes actionable in any way, the purported damage needs to be understood. Please remove the moreinfo tag when adding an affected jessie package and explaining how it is affected. Let me add a few hints on which packages to look for. The following packages set MARKDOWN_SUPPORT=NO: hdf5 hwloc libsbml mpich openms ppl simbody witty The following packages set MARKDOWN_SUPPORT=YES: ace apophenia apt aubio bladerf boost1.54 boost1.55 casablanca clipper cmocka colobot cpl csound cupt eigen3 elektra exiv2 feel++ fflas-ffpack freecontact gazebo gdcm geographiclib givaro glfw3 gnuradio gr-fcdproplus grass gtkspellmm imagemagick libam7xxx libburn libcaca libclaw libdatrie libdebian-installer libevdev libhmsbeagle liblo libltc libopendbx libreoffice libsdl2-gfx libsidplayfp libssh libstxxl libthai linbox litl lvtk lxc mysql-workbench ns3 ogre-1.9 openmprtl orthanc pcl psocksxx python-odf qof rapidjson rivet schroot sdformat serd simgrid sord speech-tools sratom ui-gxmlcpp ui-utilcpp v4l-utils visp vlfeat websocketpp The vast majority of build-rdeps of doxygen or doxygen-latex appear to not set MARKDOWN_SUPPORT at all. Helmut -- To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Bug#778655: doxygen: Doxygen should not enable markdown by default
Package: doxygen Version: 1.8.8-5 Severity: serious Justification: Creates broken documentation in many packages Hi, So doxygen 1.8 added support for interpreting markdown, and it does this in all normal comment blocks before applying the normal doxygen formatting. Unfortunately, they also chose to enable this by default, so any package that is building docs against this version, which didn't update the doxyconf configuration using this version, to see that this option exists and to turn it off if it breaks the generated documentation, is going to run a fairly high chance of generating fairly horribly broken docs. A quick canary for the extent of this problem is to search for: 'warning: unexpected command endcode' Which went by uncommented on (or I assume inspected) in logs such as was posted to https://bugs.debian.org/680896 and many other places. This is just one fairly common way this fails horribly, resulting in all the comments *above* a @code section being treated as code, and the code section itself being dumped literally to the output - but there are quite a few other ways this will generate awful unreadable documentation when markdown syntax is inadvertently applied to an existing codebase. Unless we want to ship with a lot of fairly useless -doc packages, it seems like this should probably be disabled by default, until people have become more aware of the problem and have taken steps to avoid it in their own source. I found a lot of build logs that show people having this problem, but no discussion of the cause, the impact, or the fix. I suspect a lot of people who build -doc packages rarely or never actually read them themselves ... Fixing the ones that are already broken is probably going to be something of a major operation in its own right, but the mood in #d-d seemed to be that we should start by limiting the damage here and then tackle that part separately. Ron -- To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
