Re: [PATCH rtems-docs v2 1/2] Added FAQ page

[Chris Johns]

On 4/4/21 1:30 pm, Ayushman Mishra wrote:
> Using "-" makes H4 size headings
> (https://documentation-style-guide-sphinx.readthedocs.io/en/latest/style-guide.html#headings).
> 
> Could there be a single FAQ section and then internal references, ie
> links? : Does it mean making separate .rst pages for each question
> (whose answers were previously written in faq page) and the reader
> will only see hyper-link questions , and regarding cross-link
> questions written single line example: " Please refer section
> "Creating a Patch" of RTEMS Software Engineering manual in
> https://docs.rtems.org/ ".

A single faq.rst is fine. Can there be a single single section and in that you
create anchors and links to them without having section headers?

Chris
___
devel mailing list
devel@rtems.org
http://lists.rtems.org/mailman/listinfo/devel

Re: [PATCH rtems-docs v2 1/2] Added FAQ page

[Ayushman Mishra]

Using "-" makes H4 size headings
(https://documentation-style-guide-sphinx.readthedocs.io/en/latest/style-guide.html#headings).

Could there be a single FAQ section and then internal references, ie
links? : Does it mean making separate .rst pages for each question
(whose answers were previously written in faq page) and the reader
will only see hyper-link questions , and regarding cross-link
questions written single line example: " Please refer section
"Creating a Patch" of RTEMS Software Engineering manual in
https://docs.rtems.org/ ".

On Sun, Apr 4, 2021 at 7:34 AM Chris Johns  wrote:
>
> On 4/4/21 10:37 am, Ayushman Mishra wrote:
> > Sir, can you please clarify a little bit what does "each question needs to 
> > be a
> > section heading of some level" mean , because sir I have used  this "-" 
> > line
> > below every question which is a symbol used for showing the sentence as a
> > heading in sphinx document and after building the questions are 
> > automatically
> > shown as 2.10.1, 2.10.2 ... (upto total questions).
>
> Oh yes it does. Sorry about that.
>
> Hmmm what does this do to the size of the table of contents for HTML and PDF?
>
> I have shortened the length of section headers in the past to remove words 
> that
> are not needed to make the columns and TOCs a manageable width.
>
> I am not sure how this could handled in this context with these questions?
>
> Could there be a single FAQ section and then internal references, ie links?
> Internal links are ok. And also a link back to the question list after each
> question?
>
> Chris
>
___
devel mailing list
devel@rtems.org
http://lists.rtems.org/mailman/listinfo/devel

Re: [PATCH rtems-docs v2 1/2] Added FAQ page

[Chris Johns]

On 4/4/21 10:37 am, Ayushman Mishra wrote:
> Sir, can you please clarify a little bit what does "each question needs to be 
> a
> section heading of some level" mean , because sir I have used  this "-" 
> line
> below every question which is a symbol used for showing the sentence as a
> heading in sphinx document and after building the questions are automatically
> shown as 2.10.1, 2.10.2 ... (upto total questions).  

Oh yes it does. Sorry about that.

Hmmm what does this do to the size of the table of contents for HTML and PDF?

I have shortened the length of section headers in the past to remove words that
are not needed to make the columns and TOCs a manageable width.

I am not sure how this could handled in this context with these questions?

Could there be a single FAQ section and then internal references, ie links?
Internal links are ok. And also a link back to the question list after each
question?

Chris

___
devel mailing list
devel@rtems.org
http://lists.rtems.org/mailman/listinfo/devel

Re: [PATCH rtems-docs v2 1/2] Added FAQ page

[Chris Johns]

On 4/4/21 10:55 am, Ayushman Mishra wrote:
> And sir ,

Chris is fine. I appreciate you using a formal name but in RTEMS there is no
need. You are welcome here as a member of the community just like me. :)

> if we can't use cross-link should I write a sentence like
> for eg. " (Please refer section 6.1.12. "Creating a Patch" of RTEMS
> Software Engineering manual in :r:url:`docs`) for question How do I
> make a patch? "

I think referring to the section name is best because the section number can and
will change and adding a specific section number creates an untracked 
dependency.

What you are attempting to do is appropriate and wanted however what we have at
the moment in our documentation framework does not support it. I would like to
tackle this and see how we could manage crosslinks in a scalable and
multi-format way but it is low on my queue of things to do.

Chris

> 
> On Sun, Apr 4, 2021 at 5:05 AM Chris Johns  wrote:
>>
>>
>>
>> On 3/4/21 6:25 am, Gedare Bloom wrote:
>>> On Fri, Apr 2, 2021 at 12:19 PM Ayushman Mishra
>>>  wrote:

 ---
  user/bld/index.rst   |   2 +
  user/overview/index.rst  |   2 +
  user/start/faq.rst   | 295 +++
  user/start/index.rst |   1 +
  user/support/contrib.rst |  96 +-
  user/support/support-project.rst |   2 +
  6 files changed, 303 insertions(+), 95 deletions(-)
  create mode 100644 user/start/faq.rst

 diff --git a/user/bld/index.rst b/user/bld/index.rst
 index ebedf5a..0cccde2 100644
 --- a/user/bld/index.rst
 +++ b/user/bld/index.rst
 @@ -284,6 +284,8 @@ example configuration file, building of the tests is 
 enabled for the

  [riscv/griscv]

 +.. _Migration_from_AutoconfAutomake:
 +
  Migration from Autoconf/Automake
  

 diff --git a/user/overview/index.rst b/user/overview/index.rst
 index 550724a..0703ede 100644
 --- a/user/overview/index.rst
 +++ b/user/overview/index.rst
 @@ -20,6 +20,8 @@ You are someone looking for a real-time operating 
 system.  This document

  - helps you to build an example application on top of RTEMS.

 +.. _Features:
 +
  Features
  

 diff --git a/user/start/faq.rst b/user/start/faq.rst
 new file mode 100644
 index 000..910ef8b
 --- /dev/null
 +++ b/user/start/faq.rst
 @@ -0,0 +1,295 @@
 +Frequently Asked Questions
 +==
 +
 +What is RTEMS ?
>>> No whitespace before punctuation. "What is RTEMS?"
>>>
 +---
 +
 +RTEMS is an open source real-time executive which provides a high 
 performance
 +environment for embedded real-time applications including many features.
 +
 +The RTEMS Project is the umbrella term used to describe the collection of
 +individuals, companies, universities, and research institutions that 
 collectively
 +maintain and enhance the RTEMS software base.
 +
 +RTEMS is designed to support applications with the most stringent 
 real-time
 +requirements while being compatible with open standards such as POSIX.
 +RTEMS includes optional functional features such as TCP/IP and various 
 file
 +systems while still offering minimum executable sizes under 20 KB in 
 useful
 +configurations.
 +
 +:ref:`More Features`
 +
 +Where can I get RTEMS ?
 +-
 +
 +:ref:`Downloading RTEMS`
 +
>>>
>>> What happened to:
>>> How can I pronounce RTEMS like Joel?
>>>
>>>
 +What does RTEMS stand for ?
 +-
 +
 +RTEMS is an an acronym for the Real-Time Executive for Multiprocessor 
 Systems.
>>> "an an" (typo in original wiki page :)
>>>
 +
 +Initially RTEMS stood for the Real-Time Executive for Missile Systems but 
 as it
 +became clear that the application domains that could use RTEMS extended 
 far
 +beyond missiles, the "M" changed to mean Military. When maintenance of 
 RTEMS
 +transferred to OAR, the "M" was changed again to Multiprocessor.
 +
 +At one point, there were both Ada and C implementations of RTEMS.
 +Version 3.2.1 was the last RTEMS version to have implementations in both
 +languages. Supporting the Classic API Ada implementation was painful and 
 fraught
 +with compiler specific pitfalls. With version 3.5.x, the POSIX API was 
 added as
 +the means to support the GNU Ada Translator (GNAT). This effectively 
 eliminated
 +the need for an implementation in Ada as the C implementation could 
 effectively
 +support both languages.
 +
 +Are there restrictions on the RTEMS License ?
 

Re: [PATCH rtems-docs v2 1/2] Added FAQ page

[Ayushman Mishra]

And sir , if we can't use cross-link should I write a sentence like
for eg. " (Please refer section 6.1.12. "Creating a Patch" of RTEMS
Software Engineering manual in :r:url:`docs`) for question How do I
make a patch? "

On Sun, Apr 4, 2021 at 5:05 AM Chris Johns  wrote:
>
>
>
> On 3/4/21 6:25 am, Gedare Bloom wrote:
> > On Fri, Apr 2, 2021 at 12:19 PM Ayushman Mishra
> >  wrote:
> >>
> >> ---
> >>  user/bld/index.rst   |   2 +
> >>  user/overview/index.rst  |   2 +
> >>  user/start/faq.rst   | 295 +++
> >>  user/start/index.rst |   1 +
> >>  user/support/contrib.rst |  96 +-
> >>  user/support/support-project.rst |   2 +
> >>  6 files changed, 303 insertions(+), 95 deletions(-)
> >>  create mode 100644 user/start/faq.rst
> >>
> >> diff --git a/user/bld/index.rst b/user/bld/index.rst
> >> index ebedf5a..0cccde2 100644
> >> --- a/user/bld/index.rst
> >> +++ b/user/bld/index.rst
> >> @@ -284,6 +284,8 @@ example configuration file, building of the tests is 
> >> enabled for the
> >>
> >>  [riscv/griscv]
> >>
> >> +.. _Migration_from_AutoconfAutomake:
> >> +
> >>  Migration from Autoconf/Automake
> >>  
> >>
> >> diff --git a/user/overview/index.rst b/user/overview/index.rst
> >> index 550724a..0703ede 100644
> >> --- a/user/overview/index.rst
> >> +++ b/user/overview/index.rst
> >> @@ -20,6 +20,8 @@ You are someone looking for a real-time operating 
> >> system.  This document
> >>
> >>  - helps you to build an example application on top of RTEMS.
> >>
> >> +.. _Features:
> >> +
> >>  Features
> >>  
> >>
> >> diff --git a/user/start/faq.rst b/user/start/faq.rst
> >> new file mode 100644
> >> index 000..910ef8b
> >> --- /dev/null
> >> +++ b/user/start/faq.rst
> >> @@ -0,0 +1,295 @@
> >> +Frequently Asked Questions
> >> +==
> >> +
> >> +What is RTEMS ?
> > No whitespace before punctuation. "What is RTEMS?"
> >
> >> +---
> >> +
> >> +RTEMS is an open source real-time executive which provides a high 
> >> performance
> >> +environment for embedded real-time applications including many features.
> >> +
> >> +The RTEMS Project is the umbrella term used to describe the collection of
> >> +individuals, companies, universities, and research institutions that 
> >> collectively
> >> +maintain and enhance the RTEMS software base.
> >> +
> >> +RTEMS is designed to support applications with the most stringent 
> >> real-time
> >> +requirements while being compatible with open standards such as POSIX.
> >> +RTEMS includes optional functional features such as TCP/IP and various 
> >> file
> >> +systems while still offering minimum executable sizes under 20 KB in 
> >> useful
> >> +configurations.
> >> +
> >> +:ref:`More Features`
> >> +
> >> +Where can I get RTEMS ?
> >> +-
> >> +
> >> +:ref:`Downloading RTEMS`
> >> +
> >
> > What happened to:
> > How can I pronounce RTEMS like Joel?
> >
> >
> >> +What does RTEMS stand for ?
> >> +-
> >> +
> >> +RTEMS is an an acronym for the Real-Time Executive for Multiprocessor 
> >> Systems.
> > "an an" (typo in original wiki page :)
> >
> >> +
> >> +Initially RTEMS stood for the Real-Time Executive for Missile Systems but 
> >> as it
> >> +became clear that the application domains that could use RTEMS extended 
> >> far
> >> +beyond missiles, the "M" changed to mean Military. When maintenance of 
> >> RTEMS
> >> +transferred to OAR, the "M" was changed again to Multiprocessor.
> >> +
> >> +At one point, there were both Ada and C implementations of RTEMS.
> >> +Version 3.2.1 was the last RTEMS version to have implementations in both
> >> +languages. Supporting the Classic API Ada implementation was painful and 
> >> fraught
> >> +with compiler specific pitfalls. With version 3.5.x, the POSIX API was 
> >> added as
> >> +the means to support the GNU Ada Translator (GNAT). This effectively 
> >> eliminated
> >> +the need for an implementation in Ada as the C implementation could 
> >> effectively
> >> +support both languages.
> >> +
> >> +Are there restrictions on the RTEMS License ?
> >> +
> >> +
> >> +RTEMS RTEMS is licensed under a combination of permissive licenses and a
> >> +modified version of the GNU General Public License (GPL).
> >> +For source code "Two Clause BSD” (BSD-2-Clause) and
> >> +for documentation CC-BY-SA-4.0 license is preferred.
> >> +The modification places no restrictions on the applications which use 
> >> RTEMS but
> >> +protects the interests of those who work on RTEMS.
> >> +
> >> +`License in RTEMS
> >> + >> +license-requirements.html>`__
> >> +
> >
> > add the other questions even if their pages are missing, and maybe add
> > a "TBD" stub or something so someone can 

Re: [PATCH rtems-docs v2 1/2] Added FAQ page

[Ayushman Mishra]

Sir, can you please clarify a little bit what does "each question needs to
be a section heading of some level" mean , because sir I have used  this
"-" line below every question which is a symbol used for showing the
sentence as a heading in sphinx document and after building the questions
are automatically shown as 2.10.1, 2.10.2 ... (upto total questions).

On Sun, Apr 4, 2021, 5:05 AM Chris Johns  wrote:

>
>
> On 3/4/21 6:25 am, Gedare Bloom wrote:
> > On Fri, Apr 2, 2021 at 12:19 PM Ayushman Mishra
> >  wrote:
> >>
> >> ---
> >>  user/bld/index.rst   |   2 +
> >>  user/overview/index.rst  |   2 +
> >>  user/start/faq.rst   | 295 +++
> >>  user/start/index.rst |   1 +
> >>  user/support/contrib.rst |  96 +-
> >>  user/support/support-project.rst |   2 +
> >>  6 files changed, 303 insertions(+), 95 deletions(-)
> >>  create mode 100644 user/start/faq.rst
> >>
> >> diff --git a/user/bld/index.rst b/user/bld/index.rst
> >> index ebedf5a..0cccde2 100644
> >> --- a/user/bld/index.rst
> >> +++ b/user/bld/index.rst
> >> @@ -284,6 +284,8 @@ example configuration file, building of the tests
> is enabled for the
> >>
> >>  [riscv/griscv]
> >>
> >> +.. _Migration_from_AutoconfAutomake:
> >> +
> >>  Migration from Autoconf/Automake
> >>  
> >>
> >> diff --git a/user/overview/index.rst b/user/overview/index.rst
> >> index 550724a..0703ede 100644
> >> --- a/user/overview/index.rst
> >> +++ b/user/overview/index.rst
> >> @@ -20,6 +20,8 @@ You are someone looking for a real-time operating
> system.  This document
> >>
> >>  - helps you to build an example application on top of RTEMS.
> >>
> >> +.. _Features:
> >> +
> >>  Features
> >>  
> >>
> >> diff --git a/user/start/faq.rst b/user/start/faq.rst
> >> new file mode 100644
> >> index 000..910ef8b
> >> --- /dev/null
> >> +++ b/user/start/faq.rst
> >> @@ -0,0 +1,295 @@
> >> +Frequently Asked Questions
> >> +==
> >> +
> >> +What is RTEMS ?
> > No whitespace before punctuation. "What is RTEMS?"
> >
> >> +---
> >> +
> >> +RTEMS is an open source real-time executive which provides a high
> performance
> >> +environment for embedded real-time applications including many
> features.
> >> +
> >> +The RTEMS Project is the umbrella term used to describe the collection
> of
> >> +individuals, companies, universities, and research institutions that
> collectively
> >> +maintain and enhance the RTEMS software base.
> >> +
> >> +RTEMS is designed to support applications with the most stringent
> real-time
> >> +requirements while being compatible with open standards such as POSIX.
> >> +RTEMS includes optional functional features such as TCP/IP and various
> file
> >> +systems while still offering minimum executable sizes under 20 KB in
> useful
> >> +configurations.
> >> +
> >> +:ref:`More Features`
> >> +
> >> +Where can I get RTEMS ?
> >> +-
> >> +
> >> +:ref:`Downloading RTEMS`
> >> +
> >
> > What happened to:
> > How can I pronounce RTEMS like Joel?
> >
> >
> >> +What does RTEMS stand for ?
> >> +-
> >> +
> >> +RTEMS is an an acronym for the Real-Time Executive for Multiprocessor
> Systems.
> > "an an" (typo in original wiki page :)
> >
> >> +
> >> +Initially RTEMS stood for the Real-Time Executive for Missile Systems
> but as it
> >> +became clear that the application domains that could use RTEMS
> extended far
> >> +beyond missiles, the "M" changed to mean Military. When maintenance of
> RTEMS
> >> +transferred to OAR, the "M" was changed again to Multiprocessor.
> >> +
> >> +At one point, there were both Ada and C implementations of RTEMS.
> >> +Version 3.2.1 was the last RTEMS version to have implementations in
> both
> >> +languages. Supporting the Classic API Ada implementation was painful
> and fraught
> >> +with compiler specific pitfalls. With version 3.5.x, the POSIX API was
> added as
> >> +the means to support the GNU Ada Translator (GNAT). This effectively
> eliminated
> >> +the need for an implementation in Ada as the C implementation could
> effectively
> >> +support both languages.
> >> +
> >> +Are there restrictions on the RTEMS License ?
> >> +
> >> +
> >> +RTEMS RTEMS is licensed under a combination of permissive licenses and
> a
> >> +modified version of the GNU General Public License (GPL).
> >> +For source code "Two Clause BSD” (BSD-2-Clause) and
> >> +for documentation CC-BY-SA-4.0 license is preferred.
> >> +The modification places no restrictions on the applications which use
> RTEMS but
> >> +protects the interests of those who work on RTEMS.
> >> +
> >> +`License in RTEMS
> >> + >> +license-requirements.html>`__
> >> +
> >
> > add the other questions even if 

Re: [PATCH rtems-docs v2 1/2] Added FAQ page

[Chris Johns]

On 3/4/21 6:25 am, Gedare Bloom wrote:
> On Fri, Apr 2, 2021 at 12:19 PM Ayushman Mishra
>  wrote:
>>
>> ---
>>  user/bld/index.rst   |   2 +
>>  user/overview/index.rst  |   2 +
>>  user/start/faq.rst   | 295 +++
>>  user/start/index.rst |   1 +
>>  user/support/contrib.rst |  96 +-
>>  user/support/support-project.rst |   2 +
>>  6 files changed, 303 insertions(+), 95 deletions(-)
>>  create mode 100644 user/start/faq.rst
>>
>> diff --git a/user/bld/index.rst b/user/bld/index.rst
>> index ebedf5a..0cccde2 100644
>> --- a/user/bld/index.rst
>> +++ b/user/bld/index.rst
>> @@ -284,6 +284,8 @@ example configuration file, building of the tests is 
>> enabled for the
>>
>>  [riscv/griscv]
>>
>> +.. _Migration_from_AutoconfAutomake:
>> +
>>  Migration from Autoconf/Automake
>>  
>>
>> diff --git a/user/overview/index.rst b/user/overview/index.rst
>> index 550724a..0703ede 100644
>> --- a/user/overview/index.rst
>> +++ b/user/overview/index.rst
>> @@ -20,6 +20,8 @@ You are someone looking for a real-time operating system.  
>> This document
>>
>>  - helps you to build an example application on top of RTEMS.
>>
>> +.. _Features:
>> +
>>  Features
>>  
>>
>> diff --git a/user/start/faq.rst b/user/start/faq.rst
>> new file mode 100644
>> index 000..910ef8b
>> --- /dev/null
>> +++ b/user/start/faq.rst
>> @@ -0,0 +1,295 @@
>> +Frequently Asked Questions
>> +==
>> +
>> +What is RTEMS ?
> No whitespace before punctuation. "What is RTEMS?"
> 
>> +---
>> +
>> +RTEMS is an open source real-time executive which provides a high 
>> performance
>> +environment for embedded real-time applications including many features.
>> +
>> +The RTEMS Project is the umbrella term used to describe the collection of
>> +individuals, companies, universities, and research institutions that 
>> collectively
>> +maintain and enhance the RTEMS software base.
>> +
>> +RTEMS is designed to support applications with the most stringent real-time
>> +requirements while being compatible with open standards such as POSIX.
>> +RTEMS includes optional functional features such as TCP/IP and various file
>> +systems while still offering minimum executable sizes under 20 KB in useful
>> +configurations.
>> +
>> +:ref:`More Features`
>> +
>> +Where can I get RTEMS ?
>> +-
>> +
>> +:ref:`Downloading RTEMS`
>> +
> 
> What happened to:
> How can I pronounce RTEMS like Joel?
> 
> 
>> +What does RTEMS stand for ?
>> +-
>> +
>> +RTEMS is an an acronym for the Real-Time Executive for Multiprocessor 
>> Systems.
> "an an" (typo in original wiki page :)
> 
>> +
>> +Initially RTEMS stood for the Real-Time Executive for Missile Systems but 
>> as it
>> +became clear that the application domains that could use RTEMS extended far
>> +beyond missiles, the "M" changed to mean Military. When maintenance of RTEMS
>> +transferred to OAR, the "M" was changed again to Multiprocessor.
>> +
>> +At one point, there were both Ada and C implementations of RTEMS.
>> +Version 3.2.1 was the last RTEMS version to have implementations in both
>> +languages. Supporting the Classic API Ada implementation was painful and 
>> fraught
>> +with compiler specific pitfalls. With version 3.5.x, the POSIX API was 
>> added as
>> +the means to support the GNU Ada Translator (GNAT). This effectively 
>> eliminated
>> +the need for an implementation in Ada as the C implementation could 
>> effectively
>> +support both languages.
>> +
>> +Are there restrictions on the RTEMS License ?
>> +
>> +
>> +RTEMS RTEMS is licensed under a combination of permissive licenses and a
>> +modified version of the GNU General Public License (GPL).
>> +For source code "Two Clause BSD” (BSD-2-Clause) and
>> +for documentation CC-BY-SA-4.0 license is preferred.
>> +The modification places no restrictions on the applications which use RTEMS 
>> but
>> +protects the interests of those who work on RTEMS.
>> +
>> +`License in RTEMS
>> +> +license-requirements.html>`__
>> +
> 
> add the other questions even if their pages are missing, and maybe add
> a "TBD" stub or something so someone can provide the answers.
> 
> Here would be "Are there Export Restrictions? on RTEMS?"
> 
>> +What standards are supported by RTEMS?
>> +-
>> +
>> +The original "Classic" RTEMS API is based on the Real-Time Executive 
>> Interface
>> +Definition (RTEID) and the Open Real-Time Kernel Interface Definition 
>> (ORKID).
>> +RTEMS also includes support for POSIX threads and real-time extensions.
>> +
>> +With the addition of file system infrastructure, RTEMS supports 
>> approximately
>> +80% of the 

Re: [PATCH rtems-docs v2 1/2] Added FAQ page

[Joel Sherrill]

On Fri, Apr 2, 2021 at 2:26 PM Gedare Bloom  wrote:

> On Fri, Apr 2, 2021 at 12:19 PM Ayushman Mishra
>  wrote:
> >
> > ---
> >  user/bld/index.rst   |   2 +
> >  user/overview/index.rst  |   2 +
> >  user/start/faq.rst   | 295 +++
> >  user/start/index.rst |   1 +
> >  user/support/contrib.rst |  96 +-
> >  user/support/support-project.rst |   2 +
> >  6 files changed, 303 insertions(+), 95 deletions(-)
> >  create mode 100644 user/start/faq.rst
> >
> > diff --git a/user/bld/index.rst b/user/bld/index.rst
> > index ebedf5a..0cccde2 100644
> > --- a/user/bld/index.rst
> > +++ b/user/bld/index.rst
> > @@ -284,6 +284,8 @@ example configuration file, building of the tests is
> enabled for the
> >
> >  [riscv/griscv]
> >
> > +.. _Migration_from_AutoconfAutomake:
> > +
> >  Migration from Autoconf/Automake
> >  
> >
> > diff --git a/user/overview/index.rst b/user/overview/index.rst
> > index 550724a..0703ede 100644
> > --- a/user/overview/index.rst
> > +++ b/user/overview/index.rst
> > @@ -20,6 +20,8 @@ You are someone looking for a real-time operating
> system.  This document
> >
> >  - helps you to build an example application on top of RTEMS.
> >
> > +.. _Features:
> > +
> >  Features
> >  
> >
> > diff --git a/user/start/faq.rst b/user/start/faq.rst
> > new file mode 100644
> > index 000..910ef8b
> > --- /dev/null
> > +++ b/user/start/faq.rst
> > @@ -0,0 +1,295 @@
> > +Frequently Asked Questions
> > +==
> > +
> > +What is RTEMS ?
> No whitespace before punctuation. "What is RTEMS?"
>
> > +---
> > +
> > +RTEMS is an open source real-time executive which provides a high
> performance
> > +environment for embedded real-time applications including many features.
> > +
> > +The RTEMS Project is the umbrella term used to describe the collection
> of
> > +individuals, companies, universities, and research institutions that
> collectively
> > +maintain and enhance the RTEMS software base.
> > +
> > +RTEMS is designed to support applications with the most stringent
> real-time
> > +requirements while being compatible with open standards such as POSIX.
> > +RTEMS includes optional functional features such as TCP/IP and various
> file
> > +systems while still offering minimum executable sizes under 20 KB in
> useful
> > +configurations.
> > +
> > +:ref:`More Features`
> > +
> > +Where can I get RTEMS ?
> > +-
> > +
> > +:ref:`Downloading RTEMS`
> > +
>
> What happened to:
> How can I pronounce RTEMS like Joel?
>

 This is clearly the most important question in the FAQ <.sarcasm>

>
>
> > +What does RTEMS stand for ?
> > +-
> > +
> > +RTEMS is an an acronym for the Real-Time Executive for Multiprocessor
> Systems.
> "an an" (typo in original wiki page :)
>
> > +
> > +Initially RTEMS stood for the Real-Time Executive for Missile Systems
> but as it
> > +became clear that the application domains that could use RTEMS extended
> far
> > +beyond missiles, the "M" changed to mean Military. When maintenance of
> RTEMS
> > +transferred to OAR, the "M" was changed again to Multiprocessor.
> > +
> > +At one point, there were both Ada and C implementations of RTEMS.
> > +Version 3.2.1 was the last RTEMS version to have implementations in both
> > +languages. Supporting the Classic API Ada implementation was painful
> and fraught
> > +with compiler specific pitfalls. With version 3.5.x, the POSIX API was
> added as
> > +the means to support the GNU Ada Translator (GNAT). This effectively
> eliminated
> > +the need for an implementation in Ada as the C implementation could
> effectively
> > +support both languages.
>

> +
> > +Are there restrictions on the RTEMS License ?
> > +
> > +
> > +RTEMS RTEMS is licensed under a combination of permissive licenses and a
> > +modified version of the GNU General Public License (GPL).
> > +For source code "Two Clause BSD” (BSD-2-Clause) and
> > +for documentation CC-BY-SA-4.0 license is preferred.
> > +The modification places no restrictions on the applications which use
> RTEMS but
> > +protects the interests of those who work on RTEMS.
> > +
> > +`License in RTEMS
> > + > +license-requirements.html>`__
> > +
>
> add the other questions even if their pages are missing, and maybe add
> a "TBD" stub or something so someone can provide the answers.
>
> Here would be "Are there Export Restrictions? on RTEMS?"
>
> > +What standards are supported by RTEMS?
> > +-
> > +
> > +The original "Classic" RTEMS API is based on the Real-Time Executive
> Interface
> > +Definition (RTEID) and the Open Real-Time Kernel Interface Definition
> (ORKID).
> > +RTEMS also 

Re: [PATCH rtems-docs v2 1/2] Added FAQ page

[Gedare Bloom]

On Fri, Apr 2, 2021 at 12:19 PM Ayushman Mishra
 wrote:
>
> ---
>  user/bld/index.rst   |   2 +
>  user/overview/index.rst  |   2 +
>  user/start/faq.rst   | 295 +++
>  user/start/index.rst |   1 +
>  user/support/contrib.rst |  96 +-
>  user/support/support-project.rst |   2 +
>  6 files changed, 303 insertions(+), 95 deletions(-)
>  create mode 100644 user/start/faq.rst
>
> diff --git a/user/bld/index.rst b/user/bld/index.rst
> index ebedf5a..0cccde2 100644
> --- a/user/bld/index.rst
> +++ b/user/bld/index.rst
> @@ -284,6 +284,8 @@ example configuration file, building of the tests is 
> enabled for the
>
>  [riscv/griscv]
>
> +.. _Migration_from_AutoconfAutomake:
> +
>  Migration from Autoconf/Automake
>  
>
> diff --git a/user/overview/index.rst b/user/overview/index.rst
> index 550724a..0703ede 100644
> --- a/user/overview/index.rst
> +++ b/user/overview/index.rst
> @@ -20,6 +20,8 @@ You are someone looking for a real-time operating system.  
> This document
>
>  - helps you to build an example application on top of RTEMS.
>
> +.. _Features:
> +
>  Features
>  
>
> diff --git a/user/start/faq.rst b/user/start/faq.rst
> new file mode 100644
> index 000..910ef8b
> --- /dev/null
> +++ b/user/start/faq.rst
> @@ -0,0 +1,295 @@
> +Frequently Asked Questions
> +==
> +
> +What is RTEMS ?
No whitespace before punctuation. "What is RTEMS?"

> +---
> +
> +RTEMS is an open source real-time executive which provides a high performance
> +environment for embedded real-time applications including many features.
> +
> +The RTEMS Project is the umbrella term used to describe the collection of
> +individuals, companies, universities, and research institutions that 
> collectively
> +maintain and enhance the RTEMS software base.
> +
> +RTEMS is designed to support applications with the most stringent real-time
> +requirements while being compatible with open standards such as POSIX.
> +RTEMS includes optional functional features such as TCP/IP and various file
> +systems while still offering minimum executable sizes under 20 KB in useful
> +configurations.
> +
> +:ref:`More Features`
> +
> +Where can I get RTEMS ?
> +-
> +
> +:ref:`Downloading RTEMS`
> +

What happened to:
How can I pronounce RTEMS like Joel?


> +What does RTEMS stand for ?
> +-
> +
> +RTEMS is an an acronym for the Real-Time Executive for Multiprocessor 
> Systems.
"an an" (typo in original wiki page :)

> +
> +Initially RTEMS stood for the Real-Time Executive for Missile Systems but as 
> it
> +became clear that the application domains that could use RTEMS extended far
> +beyond missiles, the "M" changed to mean Military. When maintenance of RTEMS
> +transferred to OAR, the "M" was changed again to Multiprocessor.
> +
> +At one point, there were both Ada and C implementations of RTEMS.
> +Version 3.2.1 was the last RTEMS version to have implementations in both
> +languages. Supporting the Classic API Ada implementation was painful and 
> fraught
> +with compiler specific pitfalls. With version 3.5.x, the POSIX API was added 
> as
> +the means to support the GNU Ada Translator (GNAT). This effectively 
> eliminated
> +the need for an implementation in Ada as the C implementation could 
> effectively
> +support both languages.
> +
> +Are there restrictions on the RTEMS License ?
> +
> +
> +RTEMS RTEMS is licensed under a combination of permissive licenses and a
> +modified version of the GNU General Public License (GPL).
> +For source code "Two Clause BSD” (BSD-2-Clause) and
> +for documentation CC-BY-SA-4.0 license is preferred.
> +The modification places no restrictions on the applications which use RTEMS 
> but
> +protects the interests of those who work on RTEMS.
> +
> +`License in RTEMS
> + +license-requirements.html>`__
> +

add the other questions even if their pages are missing, and maybe add
a "TBD" stub or something so someone can provide the answers.

Here would be "Are there Export Restrictions? on RTEMS?"

> +What standards are supported by RTEMS?
> +-
> +
> +The original "Classic" RTEMS API is based on the Real-Time Executive 
> Interface
> +Definition (RTEID) and the Open Real-Time Kernel Interface Definition 
> (ORKID).
> +RTEMS also includes support for POSIX threads and real-time extensions.
> +
> +With the addition of file system infrastructure, RTEMS supports approximately
> +80% of the POSIX 1003.1b-1996 standard. This standard defines the programming
> +interfaces of standard UNIX. This means that much source code that works on
> +UNIX, also works on RTEMS.RTEMS includes a port of the