Re: Documentation format question

["Martin Liška" <mliska@suse.cz>]

On 5/27/22 22:05, Andrew MacLeod via Gcc wrote:
> On 5/27/22 02:38, Richard Biener wrote:
>> On Wed, May 25, 2022 at 10:36 PM Andrew MacLeod via Gcc <gcc@gcc.gnu.org> wrote:
>>> I am going to get to some documentation for ranger and its components
>>> later this cycle.
>>>
>>> I use to stick these sorts things on the wiki page, but i find that gets
>>> out of date really quickly.  I could add more comments to the top of
>>> each file, but that doesnt seem very practical for larger architectural
>>> descriptions, nor for APIs/use cases/best practices.   I could use
>>> google docs and turn it into a PDF or some other format, but that isnt
>>> very flexible.
>>>
>>> Do we/anyone have any forward looking plans for GCC documentation that I
>>> should consider using?  It would be nice to be able to tie some of it
>>> into source files/classes in some way, but I am unsure of a decent
>>> direction.  It has to be easy to use, or I wont use it :-)  And i
>>> presume many others wouldn't either.  Im not too keep an manually
>>> marking up text either.
>> The appropriate place for this is the internals manual and thus the
>> current format in use is texinfo in gcc/doc/
>>
> And there is no move to convert it to anything more modern?

Hi.

Yes, there's plan moving to Sphinx for GCC 13, but I'm currently stuck with Sphinx upsteam
where I have a pending pull requests. Hopefully, I'll return to it soon.

>    Is there at least a reasonable tool to be able to generate texinfo from?  Otherwise the higher level stuff is likely to end up in a wiki page where I can just visually do it.

But as Richi wrote, if you write it in Texinfo, then I can easily convert it (I'll be doing the same for the rest of manuals).

In your case, you can experiment with Sphinx (similarly to libgccjit), and then export texinfo, similarly to what libgccjit does.

Martin

> 
> Andrew
> 
>