Documentation format question

Documentation format question

[Andrew MacLeod]

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.

It would be nice if we had a central plan/direction that we were looking 
to adopt.  Is there such a thing I'm simply not aware of because I don't 
pay enough attention? I heard rumors on a gdb conversation that Marxin 
is dabbling/using/trying something for gcc docs?

Andrew

Re: Documentation format question

[Richard Biener]

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/

> It would be nice if we had a central plan/direction that we were looking
> to adopt.  Is there such a thing I'm simply not aware of because I don't
> pay enough attention? I heard rumors on a gdb conversation that Marxin
> is dabbling/using/trying something for gcc docs?
>
> Andrew
>
>
>

Re: Documentation format question

[Andrew MacLeod]

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?    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.

Andrew

Re: Documentation format question

[Martin Liška]

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
> 
>