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-rc-requ...@lists.debian.org with a subject of "unsubscribe". Trouble? Contact listmas...@lists.debian.org
