[PATCH 1/2] Added FAQ page

[Chris Johns]

On 6/4/21 2:26 am, Gedare Bloom wrote:
> On Sat, Apr 3, 2021 at 5:15 PM Chris Johns <chrisj at rtems.org> wrote:
>>
>> On 3/4/21 6:29 am, Gedare Bloom wrote:
>>> On Fri, Apr 2, 2021 at 12:55 PM Joel Sherrill <joel at rtems.org> wrote:
>>>> On Fri, Apr 2, 2021 at 1:50 PM Ayushman Mishra <ayushvidushi01 at gmail.com> wrote:
>>>>>
>>>>> Sir, It was given as an issue https://devel.rtems.org/ticket/3958 (
>>>>> Review wiki/TBR/Website/FAQ for correct links) for the faq page
>>>>> https://devel.rtems.org/wiki/TBR/Website/FAQ
>>>>
>>>>
>>>> Thanks for confirming that. When Gedare acks the patches as being
>>>> ok by him, I will see about removing that page and fixing links to it.
>>>>
>>>> --joel
>>>>>
>>>>>
>>>>>
>>>>> On Sat, Apr 3, 2021 at 12:10 AM Joel Sherrill <joel at rtems.org> wrote:
>>>>>>
>>>>>>
>>>>>>
>>>>>> On Fri, Apr 2, 2021 at 1:19 PM Ayushman Mishra <ayushvidushi01 at gmail.com> wrote:
>>>>>>>
>>>>>>> Greetings Sir,
>>>>>>> I have corrected and send patches regarding FAQ page in user manual.I
>>>>>>> was able to build the page on my system and also attached a
>>>>>>> screen-shot of the builded page on browser . I have corrected
>>>>>>> whitespace consistency and reference links according to other
>>>>>>> doc-pages
>>>>>>
>>>>>>
>>>>>> Random question. Is this information from the Wiki or just an update
>>>>>> of what was already in rtems-docs? If this obsoletes any information
>>>>>> in the wiki, I would like to know so we can remove it.
>>>>>>
>>>>>>>
>>>>>>> . Regarding the issue of cross-link between docs , I had
>>>>>>> sent mail on devel mail list
>>>>>>> https://lists.rtems.org/pipermail/devel/2021-March/065882.html but
>>>>>>> haven't got any response , so few days ago after a little discussion
>>>>>>> on discord vijay sir said to post the patch and someone might point it
>>>>>>> to a better way if it exists.
>>>>>>
>>>>>>
>>>>>> I don't know if we know the answer to that with Sphinx. If "we" do, then
>>>>>> I am not part of that "we".  Hopefully someone will educate us. :)
>>>>>>
>>>>>> Gedare.. is the new patch OK? It must be in another thread because
>>>>>> I don't see it here.
>>>>>>
>>>>>> --joel
>>> Patch needs a little bit of tweaking. It's close.
>>>
>>> The problem with the cross-doc links is that they are wrong for a
>>> release doc. I don't think we have determined what is the proper
>>> solution to follow yet. They also don't populate the section numbers
>>> in PDF builds, so all you get is the URL and if you have printed
>>> manuals (does anyone do that?) you might not be able to find what you
>>> want. There's no good answer to this problem though, so I'm ok with
>>> merging the patch after the other issues get addressed, but we're
>>> probably adding more effort to the release/post-release procedures
>>> until someone sorts out how to do cross-doc links in a useful way.
>>
>> Sorry no crosslinking.
>>
> 
> This is a serious limitation that has come up several times. 

I wish I had a better answer than a flat no. I could not find a solution in
sphinx. What has been offered or added to the documentation created a liability
for the releases and so was removed. All I am doing is dealing with the issue up
front.

> We should
> open a ticket for this? Sorting out how to support link generation may
> be a worthwhile SoC task?

You would need a capable high quality GSoC student. This is a complex task. The
ticket needs to technically address how to manage the install prefix, the
supported output formats plus relative URL based web hosted installs. It has to
cover how we work checking a build without installing, installed checks (ie
coverpage) and then installs on a web server, ie docs.rtems.org and then docs on
ftp.rtems.org where the final location is not known. Can a documentation set be
moved to a new base? It happens, the old releases have moved a number of times
without being regenerated. HTML could be made to work, HTML and PDF is hard.

Chris