[haiku-doc] Re: Revert doxygen to version 1.7.6
- From: John Scipione <jscipione@xxxxxxxxx>
- To: haiku-doc@xxxxxxxxxxxxx
- Date: Sat, 22 Dec 2012 17:15:37 -0500
On Sat, Dec 22, 2012 at 4:35 PM, Niels Sascha Reedijk
<niels.reedijk@xxxxxxxxx> wrote:
> Hi,
>
> On Sat, Dec 22, 2012 at 9:22 PM, John Scipione <jscipione@xxxxxxxxx> wrote:
>> Would it be possible to revert the doxygen version used on the server
>> to build the Haiku Book to 1.7.6 (latest version of 1.7.x branch).
>>
>> 1.8.0 introduced some nice new features which unfortunately break our
>> documentation. Most of the problems can be fixed by turning off
>> Markdown support. Markdown is cool but it introduces a whitespace
>> dependency that we never had before which has broken stuff.
>>
>> However, there are a few problems that cannot be so easily fixed.
>> 1.8.0 no longer indents code blocks so all code blocks are flattened
>> down each line starting all the way to the left margin. The only way
>> to fix this that I've found is to change code blocks into verbatim
>> blocks but then we lose syntax highlighting, so either way we lose
>> something.
>
> Isn't this a CSS issue?
No, nothing to do with CSS unfortunately. Doxygen changed the way
@code blocks work in 1.8.0. I guess they expect you to use Markdown
now, but it's not really the same, you lose syntax highlighting. I
could get syntax highlighting back using javascript but that is a big
change and I don't really want to update all the existing docs.
>> Given that the documentation is broken on 1.8.1 installed on the
>> server right now can we revert to 1.7.6 for the time being? We can
>> update the code to look good and then update to the 1.8.x branch again
>> later on.
>
> Yes, or not. I still want to see whether switching to the wiki
> approach will work. I am sort of stuck on finding a roadmap right now.
> I would also like to think about how we approach things like
> organizing functions and creating navigation.
I also think that is a good approach, at least I'm not in love with
Doxygen. Problem is that Doxygen seems to be the best program out
there for source code documentation. The wiki would be a good
secondary solution though. We'd lose all the code checking that
doxygen does, but the barrier to entry of fixing the docs would be
lowered. If we could get a few more people involved in documentation
writing it would be a net win.
> Will we use header files as package containers (which is not really a
> C++ convention, nor a Haiku one), or will we just use a liberal way of
> organizing it? Like putting all the support kit functions on one page?
I would organize classes by kit that seems to be the most reasonable
way to organize them.
> Anyway, I will try to downgrade the server to 1.7.6.
Okay, that will be helpful in the interim, at least the
api.haiku-os.org page will look decent again.
Other related posts:
