search

gnustep / libs-base

The GNUstep Base Library is a library of general-purpose, non-graphical Objective C objects.
https://www.gnustep.org/
GNU General Public License v2.0
931 stars 279 forks source link

[autogsdoc] should be refactored to support multiple output formats #425

Open gcasa opened 1 month ago

gcasa commented 1 month ago

As it stands autogsdoc is an excellent tool for generating documentation from GNUstep's headers, but it is limited to HTML output. Indeed, it uses some antiquated tags from older versions of HTML, namely and to name a few. I see the following issues:

  1. The current implementation of HTML generation needs to be reviewed and updated... get rid of older tags, make the generated HTML more capable of having CSS applied
  2. The generation itself needs to be looked at such that other formats could be generated for example: Markdown or formats capable of being parsed by other document generators
  3. Code cleanup

GC

rfm commented 1 month ago

Umm ... autogsdoc has never been limited to HTML output. It was designed from scratch to produce XML (specifically the gsdoc grammar in xml), on the assumption that people could xslt (or other mechanisms) to convert the XML to other formats as required, but with an extra phase to directly produce HTML from the XML. Of course anyone is welcome to provide other styles of output. That being said, the generated HTML is old fashioned, and would definitely benefit from updating, as suggested, by someone familiar with the use of CSS.

gcasa commented 1 month ago

Umm ... autogsdoc has never been limited to HTML output. It was designed from scratch to produce XML (specifically the gsdoc grammar in xml), on the assumption that people could xslt (or other mechanisms) to convert the XML to other formats as required, but with an extra phase to directly produce HTML from the XML. Of course anyone is welcome to provide other styles of output. That being said, the generated HTML is old fashioned, and would definitely benefit from updating, as suggested, by someone familiar with the use of CSS.

AH SWEET!!! That's hugely exciting. I think then, the HTML should be updated and... we should create parsers to output different formats. Nice! :). I wasn't sure if autogsdoc generated the HTML directly or not I have never worked on that tool. I apologize for my misunderstanding.