Re: [PATCH] glossary: Add terms

[Sebastian Huber]

On 29.11.23 09:13, Sebastian Huber wrote:

On 28.11.23 20:49, andrew.butterfi...@scss.tcd.ie wrote:

    +    scenario
    +        In a setting that involves many concurrent tasks that
    interleave in arbitrary
    +        ways, a scenario describes a single specific possible
    interleaving.  One
    +        interpretation of the behaviour of a concurrent system is
    the set of all its
    +        scenarios.
    +

This doesn't cover the common use case of a test scenario which is 
usually


less about threading and more about values and using a set of methods in

a particular manner.

In the context in which Sebastian asked me for this entry, the term 
`scenario` is used as described above.


But you are right that there are nuances here. In the Promela/SPIN 
based test-generation work, each
counter example we get from SPIN describes a scenario as defined 
above, and we generate C test code
that reproduces that scenario, including the precise interleaving of 
the tasks as per  that scenario.


The term scenario is used a lot in the formal verification chapter, so 
it should have an entry. Joel, do you have a suggestion to improve the 
wording?


I added an "In the context of formal verification, ..." to the term 
definition and checked it in.


--
embedded brains GmbH & Co. KG
Herr Sebastian HUBER
Dornierstr. 4
82178 Puchheim
Germany
email: sebastian.hu...@embedded-brains.de
phone: +49-89-18 94 741 - 16
fax:   +49-89-18 94 741 - 08

Registergericht: Amtsgericht München
Registernummer: HRB 157899
Vertretungsberechtigte Geschäftsführer: Peter Rasmussen, Thomas Dörfler
Unsere Datenschutzerklärung finden Sie hier:
https://embedded-brains.de/datenschutzerklaerung/
___
devel mailing list
devel@rtems.org
http://lists.rtems.org/mailman/listinfo/devel

Re: [PATCH] glossary: Add terms

[Sebastian Huber]

On 28.11.23 20:49, andrew.butterfi...@scss.tcd.ie wrote:

+    scenario
+        In a setting that involves many concurrent tasks that
interleave in arbitrary
+        ways, a scenario describes a single specific possible
interleaving.  One
+        interpretation of the behaviour of a concurrent system is
the set of all its
+        scenarios.
+

This doesn't cover the common use case of a test scenario which is usually

less about threading and more about values and using a set of methods in

a particular manner.

In the context in which Sebastian asked me for this entry, the term 
`scenario` is used as described above.


But you are right that there are nuances here. In the Promela/SPIN based 
test-generation work, each
counter example we get from SPIN describes a scenario as defined above, 
and we generate C test code
that reproduces that scenario, including the precise interleaving of the 
tasks as per  that scenario.


The term scenario is used a lot in the formal verification chapter, so 
it should have an entry. Joel, do you have a suggestion to improve the 
wording?



--
embedded brains GmbH & Co. KG
Herr Sebastian HUBER
Dornierstr. 4
82178 Puchheim
Germany
email: sebastian.hu...@embedded-brains.de
phone: +49-89-18 94 741 - 16
fax:   +49-89-18 94 741 - 08

Registergericht: Amtsgericht München
Registernummer: HRB 157899
Vertretungsberechtigte Geschäftsführer: Peter Rasmussen, Thomas Dörfler
Unsere Datenschutzerklärung finden Sie hier:
https://embedded-brains.de/datenschutzerklaerung/
___
devel mailing list
devel@rtems.org
http://lists.rtems.org/mailman/listinfo/devel

Re: [PATCH] glossary: Add terms

[Sebastian Huber]

On 28.11.23 20:31, Joel Sherrill wrote:

+    GPL
+        This term is an acronym for
+        `GNU General Public License >`__.
+
+    GPLv3
+        This term is an acronym for
+        `GNU General Public License Version 3
>`__.
+


Do we need to include an entry for the GPLv2 w/exception that is 
actually used by some RTEMS code.


I will add an entry for GPLv2.

--
embedded brains GmbH & Co. KG
Herr Sebastian HUBER
Dornierstr. 4
82178 Puchheim
Germany
email: sebastian.hu...@embedded-brains.de
phone: +49-89-18 94 741 - 16
fax:   +49-89-18 94 741 - 08

Registergericht: Amtsgericht München
Registernummer: HRB 157899
Vertretungsberechtigte Geschäftsführer: Peter Rasmussen, Thomas Dörfler
Unsere Datenschutzerklärung finden Sie hier:
https://embedded-brains.de/datenschutzerklaerung/
___
devel mailing list
devel@rtems.org
http://lists.rtems.org/mailman/listinfo/devel

Re: [PATCH] glossary: Add terms

[Sebastian Huber]

On 28.11.23 20:31, Joel Sherrill wrote:

+    formal model
+        A model of a computing component (hardware or software)
that has a
+        mathematically based :term:`semantics`.


Why is this duplicated? Don't we have a single glossary file?

There are other duplicates below. Can we have a single source of truth?


We have a single source of truth:

https://git.rtems.org/rtems-central/tree/spec-glossary/glossary

The c-user/glossary.rst contains all terms. The other documents only the 
terms used in the document.


--
embedded brains GmbH & Co. KG
Herr Sebastian HUBER
Dornierstr. 4
82178 Puchheim
Germany
email: sebastian.hu...@embedded-brains.de
phone: +49-89-18 94 741 - 16
fax:   +49-89-18 94 741 - 08

Registergericht: Amtsgericht München
Registernummer: HRB 157899
Vertretungsberechtigte Geschäftsführer: Peter Rasmussen, Thomas Dörfler
Unsere Datenschutzerklärung finden Sie hier:
https://embedded-brains.de/datenschutzerklaerung/
___
devel mailing list
devel@rtems.org
http://lists.rtems.org/mailman/listinfo/devel

Re: [PATCH] glossary: Add terms

[andrew.butterfi...@scss.tcd.ie]

From: devel  on behalf of Joel Sherrill 

Reply to: "j...@rtems.org" 
Date: Tuesday 28 November 2023 at 19:31
To: Sebastian Huber 
Cc: "devel@rtems.org" 
Subject: Re: [PATCH] glossary: Add terms



On Tue, Nov 28, 2023 at 10:27 AM Sebastian Huber 
mailto:sebastian.hu...@embedded-brains.de>> 
wrote:
---
 c-user/glossary.rst   | 50 +++
 eng/fv/approaches.rst |  2 +-
 eng/fv/overview.rst   |  6 +++---
 eng/glossary.rst  | 26 +-
 4 files changed, 75 insertions(+), 9 deletions(-)

diff --git a/c-user/glossary.rst b/c-user/glossary.rst
index 82aedcd..9a9d12c 100644
--- a/c-user/glossary.rst
+++ b/c-user/glossary.rst
@@ -1,5 +1,6 @@
 .. SPDX-License-Identifier: CC-BY-SA-4.0

+.. Copyright (C) 2022, 2023 Trinity College Dublin
 .. Copyright (C) 2020 Richi Dubey 
(richidu...@gmail.com<mailto:richidu...@gmail.com>)
 .. Copyright (C) 2015, 2023 embedded brains GmbH & Co. KG
 .. Copyright (C) 1988, 1998 On-Line Applications Research Corporation (OAR)
@@ -17,6 +18,9 @@ Glossary
 A term used to describe an object which has been created by an
 application.

+AMP
+This term is an acronym for Asymmetric Multiprocessing.
+
 APA
 This term is an acronym for Arbitrary Processor Affinity.  APA 
schedulers
 allow a thread to have an arbitrary affinity to a processor set, 
rather than
@@ -357,6 +361,10 @@ Glossary
 mathematically intensive situations.  It is typically viewed as a 
logical
 extension of the primary processor.

+formal model
+A model of a computing component (hardware or software) that has a
+mathematically based :term:`semantics`.

This is in the neighborhood of the definitions I found but is missing a word
like rigorous.

For me "mathematically based" implies "rigorous", but I think you are right to 
emphasise this

How about: "A rigorous model of " ?


+
 freed
 A resource that has been released by the application to RTEMS.

@@ -386,6 +394,14 @@ Glossary
 GNU
 This term is an acronym for `GNU's Not Unix <https://www.gnu.org/>`_.

+GPL
+This term is an acronym for
+`GNU General Public License <https://www.gnu.org/licenses>`__.
+
+GPLv3
+This term is an acronym for
+`GNU General Public License Version 3 
<https://www.gnu.org/licenses/gpl-3.0.html>`__.
+

Do we need to include an entry for the GPLv2 w/exception that is actually used 
by some RTEMS code.

 GR712RC
 The
 `GR712RC 
<https://www.gaisler.com/index.php/products/components/gr712rc>`_
@@ -511,6 +527,10 @@ Glossary
 LIFO
 This term is an acronym for :term:`Last In First Out`.

+Linear Temporal Logic
+This is a logic that states properties about (possibly infinite) 
sequences of
+states.
+
 list
 A data structure which allows for dynamic addition and removal of
 entries.  It is not statically limited to a particular size.
@@ -520,6 +540,12 @@ Glossary
 are arranged such that the least significant byte is at the lowest
 address.

+LLVM
+This term is an acronym for
+`Low Level Virtual Machine <https://www.llvm.org>`__.
+The LLVM Project is a collection of modular and reusable compiler and
+toolchain technologies.
+
 local
 An object which was created with the LOCAL attribute and is accessible
 only on the node it was created and resides upon.  In a single 
processor
@@ -541,6 +567,9 @@ Glossary
 A :term:`task` ``L`` has a lower :term:`priority` than a task ``H``, if
 task ``L`` is less important than task ``H``.

+LTL
+This term is an acronym for :term:`Linear Temporal Logic`.
+
 major number
 The index of a device driver in the Device Driver Table.

@@ -632,6 +661,9 @@ Glossary
 mathematically intensive situations.  It is typically viewed as a 
logical
 extension of the primary processor.

+OBC
+This term is an acronym for On-Board Computer.
+
 object
 In this document, this term is used to refer collectively to tasks,
 timers, message queues, partitions, regions, semaphores, ports, and 
rate
@@ -806,6 +838,10 @@ Glossary
 A term used to describe routines which do not modify themselves or 
global
 variables.

+refinement
+A *refinement* is a relationship between a specification and its
+implementation as code.
+
 region
 An RTEMS object which is used to allocate and deallocate variable size
 blocks of memory from a dynamically specified area of memory.
@@ -818,6 +854,9 @@ Glossary
 Registers are locations physically located within a component, 
typically
 used for device control or general purpose storage.

+reification
+Anothe

Re: [PATCH] glossary: Add terms

[Joel Sherrill]

On Tue, Nov 28, 2023 at 10:27 AM Sebastian Huber <
sebastian.hu...@embedded-brains.de> wrote:

> ---
>  c-user/glossary.rst   | 50 +++
>  eng/fv/approaches.rst |  2 +-
>  eng/fv/overview.rst   |  6 +++---
>  eng/glossary.rst  | 26 +-
>  4 files changed, 75 insertions(+), 9 deletions(-)
>
> diff --git a/c-user/glossary.rst b/c-user/glossary.rst
> index 82aedcd..9a9d12c 100644
> --- a/c-user/glossary.rst
> +++ b/c-user/glossary.rst
> @@ -1,5 +1,6 @@
>  .. SPDX-License-Identifier: CC-BY-SA-4.0
>
> +.. Copyright (C) 2022, 2023 Trinity College Dublin
>  .. Copyright (C) 2020 Richi Dubey (richidu...@gmail.com)
>  .. Copyright (C) 2015, 2023 embedded brains GmbH & Co. KG
>  .. Copyright (C) 1988, 1998 On-Line Applications Research Corporation
> (OAR)
> @@ -17,6 +18,9 @@ Glossary
>  A term used to describe an object which has been created by an
>  application.
>
> +AMP
> +This term is an acronym for Asymmetric Multiprocessing.
> +
>  APA
>  This term is an acronym for Arbitrary Processor Affinity.  APA
> schedulers
>  allow a thread to have an arbitrary affinity to a processor set,
> rather than
> @@ -357,6 +361,10 @@ Glossary
>  mathematically intensive situations.  It is typically viewed as a
> logical
>  extension of the primary processor.
>
> +formal model
> +A model of a computing component (hardware or software) that has a
> +mathematically based :term:`semantics`.
>

This is in the neighborhood of the definitions I found but is missing a word
like rigorous.


> +
>  freed
>  A resource that has been released by the application to RTEMS.
>
> @@ -386,6 +394,14 @@ Glossary
>  GNU
>  This term is an acronym for `GNU's Not Unix  >`_.
>
> +GPL
> +This term is an acronym for
> +`GNU General Public License `__.
> +
> +GPLv3
> +This term is an acronym for
> +`GNU General Public License Version 3 <
> https://www.gnu.org/licenses/gpl-3.0.html>`__.
> +
>

Do we need to include an entry for the GPLv2 w/exception that is actually
used by some RTEMS code.


>  GR712RC
>  The
>  `GR712RC <
> https://www.gaisler.com/index.php/products/components/gr712rc>`_
> @@ -511,6 +527,10 @@ Glossary
>  LIFO
>  This term is an acronym for :term:`Last In First Out`.
>
> +Linear Temporal Logic
> +This is a logic that states properties about (possibly infinite)
> sequences of
> +states.
> +
>  list
>  A data structure which allows for dynamic addition and removal of
>  entries.  It is not statically limited to a particular size.
> @@ -520,6 +540,12 @@ Glossary
>  are arranged such that the least significant byte is at the lowest
>  address.
>
> +LLVM
> +This term is an acronym for
> +`Low Level Virtual Machine `__.
> +The LLVM Project is a collection of modular and reusable compiler
> and
> +toolchain technologies.
> +
>  local
>  An object which was created with the LOCAL attribute and is
> accessible
>  only on the node it was created and resides upon.  In a single
> processor
> @@ -541,6 +567,9 @@ Glossary
>  A :term:`task` ``L`` has a lower :term:`priority` than a task
> ``H``, if
>  task ``L`` is less important than task ``H``.
>
> +LTL
> +This term is an acronym for :term:`Linear Temporal Logic`.
> +
>  major number
>  The index of a device driver in the Device Driver Table.
>
> @@ -632,6 +661,9 @@ Glossary
>  mathematically intensive situations.  It is typically viewed as a
> logical
>  extension of the primary processor.
>
> +OBC
> +This term is an acronym for On-Board Computer.
> +
>  object
>  In this document, this term is used to refer collectively to
> tasks,
>  timers, message queues, partitions, regions, semaphores, ports,
> and rate
> @@ -806,6 +838,10 @@ Glossary
>  A term used to describe routines which do not modify themselves
> or global
>  variables.
>
> +refinement
> +A *refinement* is a relationship between a specification and its
> +implementation as code.
> +
>  region
>  An RTEMS object which is used to allocate and deallocate variable
> size
>  blocks of memory from a dynamically specified area of memory.
> @@ -818,6 +854,9 @@ Glossary
>  Registers are locations physically located within a component,
> typically
>  used for device control or general purpose storage.
>
> +reification
> +Another term used to denote :term:`refinement`.
> +
>  remote
>  Any object that does not reside on the local node.
>
> @@ -865,6 +904,12 @@ Glossary
>  The state of a rate monotonic timer while it is being used to
> 

[PATCH] glossary: Add terms

[Sebastian Huber]

---
 c-user/glossary.rst   | 50 +++
 eng/fv/approaches.rst |  2 +-
 eng/fv/overview.rst   |  6 +++---
 eng/glossary.rst  | 26 +-
 4 files changed, 75 insertions(+), 9 deletions(-)

diff --git a/c-user/glossary.rst b/c-user/glossary.rst
index 82aedcd..9a9d12c 100644
--- a/c-user/glossary.rst
+++ b/c-user/glossary.rst
@@ -1,5 +1,6 @@
 .. SPDX-License-Identifier: CC-BY-SA-4.0
 
+.. Copyright (C) 2022, 2023 Trinity College Dublin
 .. Copyright (C) 2020 Richi Dubey (richidu...@gmail.com)
 .. Copyright (C) 2015, 2023 embedded brains GmbH & Co. KG
 .. Copyright (C) 1988, 1998 On-Line Applications Research Corporation (OAR)
@@ -17,6 +18,9 @@ Glossary
 A term used to describe an object which has been created by an
 application.
 
+AMP
+This term is an acronym for Asymmetric Multiprocessing.
+
 APA
 This term is an acronym for Arbitrary Processor Affinity.  APA 
schedulers
 allow a thread to have an arbitrary affinity to a processor set, 
rather than
@@ -357,6 +361,10 @@ Glossary
 mathematically intensive situations.  It is typically viewed as a 
logical
 extension of the primary processor.
 
+formal model
+A model of a computing component (hardware or software) that has a
+mathematically based :term:`semantics`.
+
 freed
 A resource that has been released by the application to RTEMS.
 
@@ -386,6 +394,14 @@ Glossary
 GNU
 This term is an acronym for `GNU's Not Unix `_.
 
+GPL
+This term is an acronym for
+`GNU General Public License `__.
+
+GPLv3
+This term is an acronym for
+`GNU General Public License Version 3 
`__.
+
 GR712RC
 The
 `GR712RC 
`_
@@ -511,6 +527,10 @@ Glossary
 LIFO
 This term is an acronym for :term:`Last In First Out`.
 
+Linear Temporal Logic
+This is a logic that states properties about (possibly infinite) 
sequences of
+states.
+
 list
 A data structure which allows for dynamic addition and removal of
 entries.  It is not statically limited to a particular size.
@@ -520,6 +540,12 @@ Glossary
 are arranged such that the least significant byte is at the lowest
 address.
 
+LLVM
+This term is an acronym for
+`Low Level Virtual Machine `__.
+The LLVM Project is a collection of modular and reusable compiler and
+toolchain technologies.
+
 local
 An object which was created with the LOCAL attribute and is accessible
 only on the node it was created and resides upon.  In a single 
processor
@@ -541,6 +567,9 @@ Glossary
 A :term:`task` ``L`` has a lower :term:`priority` than a task ``H``, if
 task ``L`` is less important than task ``H``.
 
+LTL
+This term is an acronym for :term:`Linear Temporal Logic`.
+
 major number
 The index of a device driver in the Device Driver Table.
 
@@ -632,6 +661,9 @@ Glossary
 mathematically intensive situations.  It is typically viewed as a 
logical
 extension of the primary processor.
 
+OBC
+This term is an acronym for On-Board Computer.
+
 object
 In this document, this term is used to refer collectively to tasks,
 timers, message queues, partitions, regions, semaphores, ports, and 
rate
@@ -806,6 +838,10 @@ Glossary
 A term used to describe routines which do not modify themselves or 
global
 variables.
 
+refinement
+A *refinement* is a relationship between a specification and its
+implementation as code.
+
 region
 An RTEMS object which is used to allocate and deallocate variable size
 blocks of memory from a dynamically specified area of memory.
@@ -818,6 +854,9 @@ Glossary
 Registers are locations physically located within a component, 
typically
 used for device control or general purpose storage.
 
+reification
+Another term used to denote :term:`refinement`.
+
 remote
 Any object that does not reside on the local node.
 
@@ -865,6 +904,12 @@ Glossary
 The state of a rate monotonic timer while it is being used to 
delineate a
 period.  The timer exits this state by either expiring or being 
canceled.
 
+scenario
+In a setting that involves many concurrent tasks that interleave in 
arbitrary
+ways, a scenario describes a single specific possible interleaving.  
One
+interpretation of the behaviour of a concurrent system is the set of 
all its
+scenarios.
+
 schedulable
 A set of tasks which can be guaranteed to meet their deadlines based 
upon
 a specific scheduling algorithm.
@@ 

Re: [PATCH] glossary: Add terms

[Chris Johns]

OK

On 29/9/21 8:45 pm, Sebastian Huber wrote:
> ---
>  c-user/glossary.rst | 30 ++
>  1 file changed, 30 insertions(+)
> 
> diff --git a/c-user/glossary.rst b/c-user/glossary.rst
> index f85c08c..e91e356 100644
> --- a/c-user/glossary.rst
> +++ b/c-user/glossary.rst
> @@ -101,9 +101,21 @@ Glossary
>  C++11
>  The standard ISO/IEC 14882:2011.
>  
> +C++14
> +The standard ISO/IEC 14882:2014.
> +
> +C++17
> +The standard ISO/IEC 14882:2017.
> +
> +C++20
> +The standard ISO/IEC 14882:2020.
> +
>  C11
>  The standard ISO/IEC 9899:2011.
>  
> +C17
> +The standard ISO/IEC 9899:2018.
> +
>  calling convention
>  The processor and compiler dependent rules which define the mechanism
>  used to invoke subroutines in a high-level language.  These rules 
> define
> @@ -250,6 +262,9 @@ Glossary
>  EARS
>  This term is an acronym for Easy Approach to Requirements Syntax.
>  
> +EDF
> +This term is an acronym for Earliest Deadline First.
> +
>  ELF
>  This term is an acronym for
>  `Executable and Linkable Format 
> `_.
> @@ -349,6 +364,14 @@ Glossary
>  freed
>  A resource that has been released by the application to RTEMS.
>  
> +Futex
> +This term is an abbreviation for
> +`Fast User-Space Locking 
> `_.
> +The futex support in RTEMS is provided for the barriers of the
> +:term:`OpenMP` library provided by :term:`GCC`.  It could be used to
> +implement high performance :term:`SMP` synchronization primitives 
> which
> +offer random-fairness.
> +
>  GCC
>  This term is an acronym for `GNU Compiler Collection 
> `_.
>  
> @@ -547,6 +570,9 @@ Glossary
>  This term is an acronym for
>  :term:`Multiprocessor Communications Interface Layer`.
>  
> +MrsP
> +This term is an acronym for Multiprocessor Resource-Sharing Protocol.
> +
>  multiprocessing
>  The simultaneous execution of two or more processes by a multiple
>  processor computer system.
> @@ -610,6 +636,10 @@ Glossary
>  clustered scheduling.  The ``m`` denotes the number of processors in 
> the
>  system.
>  
> +OpenMP
> +This term is an acronym for
> +`Open Multi-Processing `_.
> +
>  operating system
>  The software which controls all the computer's resources and 
> provides the
>  base upon which application programs can be written.
> 
___
devel mailing list
devel@rtems.org
http://lists.rtems.org/mailman/listinfo/devel

[PATCH] glossary: Add terms

[Sebastian Huber]

---
 c-user/glossary.rst | 30 ++
 1 file changed, 30 insertions(+)

diff --git a/c-user/glossary.rst b/c-user/glossary.rst
index f85c08c..e91e356 100644
--- a/c-user/glossary.rst
+++ b/c-user/glossary.rst
@@ -101,9 +101,21 @@ Glossary
 C++11
 The standard ISO/IEC 14882:2011.
 
+C++14
+The standard ISO/IEC 14882:2014.
+
+C++17
+The standard ISO/IEC 14882:2017.
+
+C++20
+The standard ISO/IEC 14882:2020.
+
 C11
 The standard ISO/IEC 9899:2011.
 
+C17
+The standard ISO/IEC 9899:2018.
+
 calling convention
 The processor and compiler dependent rules which define the mechanism
 used to invoke subroutines in a high-level language.  These rules 
define
@@ -250,6 +262,9 @@ Glossary
 EARS
 This term is an acronym for Easy Approach to Requirements Syntax.
 
+EDF
+This term is an acronym for Earliest Deadline First.
+
 ELF
 This term is an acronym for
 `Executable and Linkable Format 
`_.
@@ -349,6 +364,14 @@ Glossary
 freed
 A resource that has been released by the application to RTEMS.
 
+Futex
+This term is an abbreviation for
+`Fast User-Space Locking 
`_.
+The futex support in RTEMS is provided for the barriers of the
+:term:`OpenMP` library provided by :term:`GCC`.  It could be used to
+implement high performance :term:`SMP` synchronization primitives which
+offer random-fairness.
+
 GCC
 This term is an acronym for `GNU Compiler Collection 
`_.
 
@@ -547,6 +570,9 @@ Glossary
 This term is an acronym for
 :term:`Multiprocessor Communications Interface Layer`.
 
+MrsP
+This term is an acronym for Multiprocessor Resource-Sharing Protocol.
+
 multiprocessing
 The simultaneous execution of two or more processes by a multiple
 processor computer system.
@@ -610,6 +636,10 @@ Glossary
 clustered scheduling.  The ``m`` denotes the number of processors in 
the
 system.
 
+OpenMP
+This term is an acronym for
+`Open Multi-Processing `_.
+
 operating system
 The software which controls all the computer's resources and provides 
the
 base upon which application programs can be written.
-- 
2.31.1

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

[PATCH 0/5] Rework glossary of terms

[Sebastian Huber]

This patch set reworks the glossary of terms so that it can be automatically
generated from specification items.

Sebastian Huber (5):
  c-user: Use four spaces per indent level
  c-user: Clarify return code related terms
  c-user: Sort glossary terms
  c-user: Merge parition term definitions
  c-user: Add copyrights to glossary

 c-user/glossary.rst | 1295 ++-
 1 file changed, 653 insertions(+), 642 deletions(-)

-- 
2.16.4

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

Re: Glossary of Terms

[Joel Sherrill]

On Wed, Jan 8, 2020 at 12:36 PM Gedare Bloom  wrote:

> On Tue, Jan 7, 2020 at 11:34 PM Sebastian Huber
>  wrote:
> >
> >
> >
> > On 07/01/2020 17:21, Gedare Bloom wrote:
> > > On Tue, Jan 7, 2020 at 2:09 AM Sebastian Huber
> > >   wrote:
> > >> On 03/01/2020 18:16, Joel Sherrill wrote:
> > >>>
> > >>> On Fri, Jan 3, 2020, 10:22 AM Gedare Bloom  > >>> <mailto:ged...@rtems.org>> wrote:
> > >> [...]
> > >>>  I prefer we use a centralized glossary/document to generate
> individual
> > >>>  glossaries (via scripting or improving Sphinx). This will be a
> lot
> > >>>  easier to maintain.
> > >>>
> > >>>
> > >>> The DoD Architecture Framework (DoDAF) calls this an AV-2 which is a
> > >>> singular artifacr across the project for consistencyt
> > >>>
> > >>> http://acqnotes.com/acqnote/tasks/av-2-integrated-dictionary
> > >>>
> > >>> That said, you need glossaries in documents and automating pulling
> > >>> definitions and acronyms out automatically producing a glossary and
> > >>> acronym list from the master AV-2 is desirable. No one wants to
> > >>> reference a standalone glossary.
> > >>>
> > >>> There can be issues if definitions change over time because the
> single
> > >>> AV-2 can't deal with old and new. It gets confusing. I have seen a
> > >>> project where the AV-2 included history like the Oxford English
> > >>> Dictionary. It was dreadful.
> > >>>
> > >>> That's a lot of background to say this isn't a RTEMS unique problem.
> A
> > >>> central database of acronyms and definitions would be a good thing.
> If
> > >>> grep is sufficient to find word use to trigger inclusion in a
> document
> > >>> specific glossary, great.
> > >> Good, so my proposal is this:
> > >>
> > >> 1. I move c-user/glossary.rst to common/glossary.rst and include this
> > >> file as is in c-user.
> > >>
> > >> 2. The glossary.rst for the other documents is generated from
> > >> common/glossary.rst based on the :term: usage. This can start simple,
> > >> e.g. only look at the *.rst files in the document directory (e.g. no
> > >> recursive includes).
> > >>
> > > Later when a new term is added for something not in c-user, then the
> > > c-user should be updated to also derive its glossary with :term:?
> > > (Before that, we might need to double check if the current glossary
> > > terms are all defined/used in c-user with :term:.)
> >
> > The :term: is sparely used in c-user currently. It would require a bit
> > of manual work to pull in all terms via this text role.
> >
> Understood, although adding those :term: from the existing glossary
> seems like a good job for grep and sed to me.
>
> > After one night, I don't like my proposal any more. I think it would be
> > better to move the glossary terms to the RTEMS specification (e.g. in
> > the RTEMS sources "spec/glossary/*.yml") and generate the glossary.rst
> > for the documents with a script.  This gives us more flexibility and
> > removes the need for the special parser code, see:
> >
> > https://lists.rtems.org/pipermail/devel/2020-January/056811.html
> >
> > The AV-2 mentioned by Joel wants the glossary terms in categories. We
> > could add categories to the glossary specification items. This would be
> > difficult with a master glossary in reST.
> >
> Yes, putting the glossary terms in a parseable structure like YAML
> sounds sensible.
>

+1

I know I have said this to anyone who will listen in person but I think the
questions we are answering and infrastructure being built up to address
pre-qualification and high integrity development processes will be of
great value outside the RTEMS Project. As banal as glossary management
sounds, managing as recommended by DoDAF and doing it with open
source tools is a BIG deal. Similar with requirements and traceability.

Let's keep solving big problems in simple ways with open source tools. :)

--joel


>
> > --
> > Sebastian Huber, embedded brains GmbH
> >
> > Address : Dornierstr. 4, D-82178 Puchheim, Germany
> > Phone   : +49 89 189 47 41-16
> > Fax : +49 89 189 47 41-09
> > E-Mail  : sebastian.hu...@embedded-brains.de
> > PGP : Public key available on request.
> >
> > Diese Nachricht ist keine geschäftliche Mitteilung im Sinne des EHUG.
> ___
> devel mailing list
> devel@rtems.org
> http://lists.rtems.org/mailman/listinfo/devel
___
devel mailing list
devel@rtems.org
http://lists.rtems.org/mailman/listinfo/devel

Re: Glossary of Terms

[Gedare Bloom]

On Tue, Jan 7, 2020 at 11:34 PM Sebastian Huber
 wrote:
>
>
>
> On 07/01/2020 17:21, Gedare Bloom wrote:
> > On Tue, Jan 7, 2020 at 2:09 AM Sebastian Huber
> >   wrote:
> >> On 03/01/2020 18:16, Joel Sherrill wrote:
> >>>
> >>> On Fri, Jan 3, 2020, 10:22 AM Gedare Bloom  >>> <mailto:ged...@rtems.org>> wrote:
> >> [...]
> >>>  I prefer we use a centralized glossary/document to generate 
> >>> individual
> >>>  glossaries (via scripting or improving Sphinx). This will be a lot
> >>>  easier to maintain.
> >>>
> >>>
> >>> The DoD Architecture Framework (DoDAF) calls this an AV-2 which is a
> >>> singular artifacr across the project for consistencyt
> >>>
> >>> http://acqnotes.com/acqnote/tasks/av-2-integrated-dictionary
> >>>
> >>> That said, you need glossaries in documents and automating pulling
> >>> definitions and acronyms out automatically producing a glossary and
> >>> acronym list from the master AV-2 is desirable. No one wants to
> >>> reference a standalone glossary.
> >>>
> >>> There can be issues if definitions change over time because the single
> >>> AV-2 can't deal with old and new. It gets confusing. I have seen a
> >>> project where the AV-2 included history like the Oxford English
> >>> Dictionary. It was dreadful.
> >>>
> >>> That's a lot of background to say this isn't a RTEMS unique problem. A
> >>> central database of acronyms and definitions would be a good thing. If
> >>> grep is sufficient to find word use to trigger inclusion in a document
> >>> specific glossary, great.
> >> Good, so my proposal is this:
> >>
> >> 1. I move c-user/glossary.rst to common/glossary.rst and include this
> >> file as is in c-user.
> >>
> >> 2. The glossary.rst for the other documents is generated from
> >> common/glossary.rst based on the :term: usage. This can start simple,
> >> e.g. only look at the *.rst files in the document directory (e.g. no
> >> recursive includes).
> >>
> > Later when a new term is added for something not in c-user, then the
> > c-user should be updated to also derive its glossary with :term:?
> > (Before that, we might need to double check if the current glossary
> > terms are all defined/used in c-user with :term:.)
>
> The :term: is sparely used in c-user currently. It would require a bit
> of manual work to pull in all terms via this text role.
>
Understood, although adding those :term: from the existing glossary
seems like a good job for grep and sed to me.

> After one night, I don't like my proposal any more. I think it would be
> better to move the glossary terms to the RTEMS specification (e.g. in
> the RTEMS sources "spec/glossary/*.yml") and generate the glossary.rst
> for the documents with a script.  This gives us more flexibility and
> removes the need for the special parser code, see:
>
> https://lists.rtems.org/pipermail/devel/2020-January/056811.html
>
> The AV-2 mentioned by Joel wants the glossary terms in categories. We
> could add categories to the glossary specification items. This would be
> difficult with a master glossary in reST.
>
Yes, putting the glossary terms in a parseable structure like YAML
sounds sensible.

> --
> Sebastian Huber, embedded brains GmbH
>
> Address : Dornierstr. 4, D-82178 Puchheim, Germany
> Phone   : +49 89 189 47 41-16
> Fax : +49 89 189 47 41-09
> E-Mail  : sebastian.hu...@embedded-brains.de
> PGP : Public key available on request.
>
> Diese Nachricht ist keine geschäftliche Mitteilung im Sinne des EHUG.
___
devel mailing list
devel@rtems.org
http://lists.rtems.org/mailman/listinfo/devel

Re: Glossary of Terms

[Sebastian Huber]

On 07/01/2020 17:21, Gedare Bloom wrote:

On Tue, Jan 7, 2020 at 2:09 AM Sebastian Huber
  wrote:

On 03/01/2020 18:16, Joel Sherrill wrote:


On Fri, Jan 3, 2020, 10:22 AM Gedare Bloom mailto:ged...@rtems.org>> wrote:

[...]

 I prefer we use a centralized glossary/document to generate individual
 glossaries (via scripting or improving Sphinx). This will be a lot
 easier to maintain.


The DoD Architecture Framework (DoDAF) calls this an AV-2 which is a
singular artifacr across the project for consistencyt

http://acqnotes.com/acqnote/tasks/av-2-integrated-dictionary

That said, you need glossaries in documents and automating pulling
definitions and acronyms out automatically producing a glossary and
acronym list from the master AV-2 is desirable. No one wants to
reference a standalone glossary.

There can be issues if definitions change over time because the single
AV-2 can't deal with old and new. It gets confusing. I have seen a
project where the AV-2 included history like the Oxford English
Dictionary. It was dreadful.

That's a lot of background to say this isn't a RTEMS unique problem. A
central database of acronyms and definitions would be a good thing. If
grep is sufficient to find word use to trigger inclusion in a document
specific glossary, great.

Good, so my proposal is this:

1. I move c-user/glossary.rst to common/glossary.rst and include this
file as is in c-user.

2. The glossary.rst for the other documents is generated from
common/glossary.rst based on the :term: usage. This can start simple,
e.g. only look at the *.rst files in the document directory (e.g. no
recursive includes).


Later when a new term is added for something not in c-user, then the
c-user should be updated to also derive its glossary with :term:?
(Before that, we might need to double check if the current glossary
terms are all defined/used in c-user with :term:.)


The :term: is sparely used in c-user currently. It would require a bit 
of manual work to pull in all terms via this text role.


After one night, I don't like my proposal any more. I think it would be 
better to move the glossary terms to the RTEMS specification (e.g. in 
the RTEMS sources "spec/glossary/*.yml") and generate the glossary.rst 
for the documents with a script.  This gives us more flexibility and 
removes the need for the special parser code, see:


https://lists.rtems.org/pipermail/devel/2020-January/056811.html

The AV-2 mentioned by Joel wants the glossary terms in categories. We 
could add categories to the glossary specification items. This would be 
difficult with a master glossary in reST.


--
Sebastian Huber, embedded brains GmbH

Address : Dornierstr. 4, D-82178 Puchheim, Germany
Phone   : +49 89 189 47 41-16
Fax : +49 89 189 47 41-09
E-Mail  : sebastian.hu...@embedded-brains.de
PGP : Public key available on request.

Diese Nachricht ist keine geschäftliche Mitteilung im Sinne des EHUG.
___
devel mailing list
devel@rtems.org
http://lists.rtems.org/mailman/listinfo/devel

Re: Glossary of Terms

[Gedare Bloom]

On Tue, Jan 7, 2020 at 2:09 AM Sebastian Huber
 wrote:
>
> On 03/01/2020 18:16, Joel Sherrill wrote:
> >
> >
> > On Fri, Jan 3, 2020, 10:22 AM Gedare Bloom  > <mailto:ged...@rtems.org>> wrote:
> [...]
> > I prefer we use a centralized glossary/document to generate individual
> > glossaries (via scripting or improving Sphinx). This will be a lot
> > easier to maintain.
> >
> >
> > The DoD Architecture Framework (DoDAF) calls this an AV-2 which is a
> > singular artifacr across the project for consistencyt
> >
> > http://acqnotes.com/acqnote/tasks/av-2-integrated-dictionary
> >
> > That said, you need glossaries in documents and automating pulling
> > definitions and acronyms out automatically producing a glossary and
> > acronym list from the master AV-2 is desirable. No one wants to
> > reference a standalone glossary.
> >
> > There can be issues if definitions change over time because the single
> > AV-2 can't deal with old and new. It gets confusing. I have seen a
> > project where the AV-2 included history like the Oxford English
> > Dictionary. It was dreadful.
> >
> > That's a lot of background to say this isn't a RTEMS unique problem. A
> > central database of acronyms and definitions would be a good thing. If
> > grep is sufficient to find word use to trigger inclusion in a document
> > specific glossary, great.
>
> Good, so my proposal is this:
>
> 1. I move c-user/glossary.rst to common/glossary.rst and include this
> file as is in c-user.
>
> 2. The glossary.rst for the other documents is generated from
> common/glossary.rst based on the :term: usage. This can start simple,
> e.g. only look at the *.rst files in the document directory (e.g. no
> recursive includes).
>
Later when a new term is added for something not in c-user, then the
c-user should be updated to also derive its glossary with :term:?
(Before that, we might need to double check if the current glossary
terms are all defined/used in c-user with :term:.)

> --
> Sebastian Huber, embedded brains GmbH
>
> Address : Dornierstr. 4, D-82178 Puchheim, Germany
> Phone   : +49 89 189 47 41-16
> Fax : +49 89 189 47 41-09
> E-Mail  : sebastian.hu...@embedded-brains.de
> PGP : Public key available on request.
>
> Diese Nachricht ist keine geschäftliche Mitteilung im Sinne des EHUG.
___
devel mailing list
devel@rtems.org
http://lists.rtems.org/mailman/listinfo/devel

Re: Glossary of Terms

[Sebastian Huber]

On 03/01/2020 18:16, Joel Sherrill wrote:



On Fri, Jan 3, 2020, 10:22 AM Gedare Bloom > wrote:

[...]

I prefer we use a centralized glossary/document to generate individual
glossaries (via scripting or improving Sphinx). This will be a lot
easier to maintain.


The DoD Architecture Framework (DoDAF) calls this an AV-2 which is a 
singular artifacr across the project for consistencyt


http://acqnotes.com/acqnote/tasks/av-2-integrated-dictionary

That said, you need glossaries in documents and automating pulling 
definitions and acronyms out automatically producing a glossary and 
acronym list from the master AV-2 is desirable. No one wants to 
reference a standalone glossary.


There can be issues if definitions change over time because the single 
AV-2 can't deal with old and new. It gets confusing. I have seen a 
project where the AV-2 included history like the Oxford English 
Dictionary. It was dreadful.


That's a lot of background to say this isn't a RTEMS unique problem. A 
central database of acronyms and definitions would be a good thing. If 
grep is sufficient to find word use to trigger inclusion in a document 
specific glossary, great.


Good, so my proposal is this:

1. I move c-user/glossary.rst to common/glossary.rst and include this 
file as is in c-user.


2. The glossary.rst for the other documents is generated from 
common/glossary.rst based on the :term: usage. This can start simple, 
e.g. only look at the *.rst files in the document directory (e.g. no 
recursive includes).


--
Sebastian Huber, embedded brains GmbH

Address : Dornierstr. 4, D-82178 Puchheim, Germany
Phone   : +49 89 189 47 41-16
Fax : +49 89 189 47 41-09
E-Mail  : sebastian.hu...@embedded-brains.de
PGP : Public key available on request.

Diese Nachricht ist keine geschäftliche Mitteilung im Sinne des EHUG.
___
devel mailing list
devel@rtems.org
http://lists.rtems.org/mailman/listinfo/devel

Re: Glossary of Terms

[Joel Sherrill]

On Fri, Jan 3, 2020, 10:22 AM Gedare Bloom  wrote:

> On Fri, Jan 3, 2020 at 3:25 AM Sebastian Huber
>  wrote:
> >
> > On 03/01/2020 10:42, andrew.butterfi...@cs.tcd.ie wrote:
> > > Hello all, and Happy New Year!
> > >
> > >> On 3 Jan 2020, at 08:10, Sebastian Huber <
> sebastian.hu...@embedded-brains.de> wrote:
> > >>
> > >>
> > >> 1. Should we use one shared glossary which is included in all
> documents?
> > >>
> > >> 2. Do we want to use document-specific glossaries and maintain
> copy-and-paste entries by hand?
> > >>
> > >> With option 1. the glossary may contain a lot of things which are
> unrelated to a specific document. However, if the Sphinx glossary support
> gets improved, this problem may vanish. With 2. we have a maintenance
> problem, e.g. keeping the copy and paste definitions in synchronization.
> > >>
> > >> What do you think?
> > >>
> > >
> > > Can we fuse 1+2 - keep a single (master) glossary file with added tags
> "glos1", "glos2" (or whatever)
> > > We then have a script that generates the different glossaries from
> that one master?
> > >
> > > I guess the issue is how easy it is to run that script from within the
> various document build workflows.
> >
> > Yes, we can also add our own scripts to automate this. The question is
> > if we want to develop special case solutions or try to fix it in the
> > upstream Sphinx project. Using our own scripts would be much probably
> > much easier, unless someone is familiar with the Sphinx internals.
> >
> > We could for example get the terms used in a document and based on this
> > generate a document-specific glossary from a master template, e.g.
> >
> > grep -r --include='*.rst' ':term:`[^`]*`' -o
> > eng/req-eng.rst::term:`GNAT`
> > eng/req-eng.rst::term:`EARS`
> > eng/req-eng.rst::term:`API`
> > eng/req-eng.rst::term:`ABI`
> > eng/req-eng.rst::term:`source code`
> > eng/req-eng.rst::term:`CCB`
> > eng/req-eng.rst::term:`ISVV`
> > eng/req-eng.rst::term:`ReqIF`
> > eng/req-eng.rst::term:`Doorstop`
> > eng/req-eng.rst::term:`Doorstop`
> > eng/req-eng.rst::term:`YAML`
> > c-user/key_concepts.rst::term:`thread`
> > c-user/symmetric_multiprocessing_services.rst::term:`TLS`
> > c-user/symmetric_multiprocessing_services.rst::term:`C11`
> > c-user/symmetric_multiprocessing_services.rst::term:`MCS`
> > c-user/symmetric_multiprocessing_services.rst::term:`FIFO`
> > c-user/symmetric_multiprocessing_services.rst::term:`NUMA`
> > c-user/symmetric_multiprocessing_services.rst::term:`TCB`
> > c-user/symmetric_multiprocessing_services.rst::term:`TTAS`
> > c-user/glossary.rst::term:`C11`
> > c-user/glossary.rst::term:`C11`
> > c-user/glossary.rst::term:`C++11`
> > user/start/prefixes.rst::term:`prefix`
> > user/installation/project-sandboxing.rst::term:`prefix`
> > user/overview/index.rst::term:`RTEMS`
> > user/overview/index.rst::term:`SMP`
> > user/overview/index.rst::term:`APIs `
> > user/overview/index.rst::term:`POSIX`
> > user/overview/index.rst::term:`C11`
> > user/overview/index.rst::term:`C++11`
> > user/overview/index.rst::term:`GCC`
> > user/overview/index.rst::term:`EMB²`
> > user/overview/index.rst::term:`OpenMP`
> > user/overview/index.rst::term:`Futex`
> > user/overview/index.rst::term:`OpenMP`
> > user/overview/index.rst::term:`OMIP`
> > user/overview/index.rst::term:`MrsP`
> > user/overview/index.rst::term:`TLS`
> > user/overview/index.rst::term:`EDF`
> > user/overview/index.rst::term:`EDF`
> > user/overview/index.rst::term:`APA`
> > user/overview/index.rst::term:`IMFS`
> > user/overview/index.rst::term:`FAT`
> > user/overview/index.rst::term:`RFS`
> > user/overview/index.rst::term:`NFSv2`
> > user/overview/index.rst::term:`JFFS2`
> > user/overview/index.rst::term:`YAFFS2`
> > user/hardware/architectures.rst::term:`ABI`
> > eclipse/overview.rst::term:`RTEMS`
> >
> > An include if used policy is not followed by the Classic API Guide since
> > this feature was not available in the old texinfo framework as well.
> >
>
> I prefer we use a centralized glossary/document to generate individual
> glossaries (via scripting or improving Sphinx). This will be a lot
> easier to maintain.
>

The DoD Architecture Framework (DoDAF) calls this an AV-2 which is a
singular artifacr across the project for consistencyt

http://acqnotes.com/acqnote/tasks/av-2-integrated-dictionary

That said, you need glossaries in documents and automating pulling
definitions and acronyms out automatically producing a glossary and acronym
list from the master AV-2 is desirable. No one wants to reference a
standalone glossary.

There can be issues if definitions change over time because the single AV-2
can't deal with old and new. It gets confusing. I have seen a project where
the AV-2 included history like the Oxford English Dictionary. It was
dreadful.

That's a lot of background to say this isn't a RTEMS unique problem. A
central database of acronyms and definitions would be a good thing. If grep
is sufficient to find word use to trigger inclusion in a document specific

Re: Glossary of Terms

[Gedare Bloom]

On Fri, Jan 3, 2020 at 3:25 AM Sebastian Huber
 wrote:
>
> On 03/01/2020 10:42, andrew.butterfi...@cs.tcd.ie wrote:
> > Hello all, and Happy New Year!
> >
> >> On 3 Jan 2020, at 08:10, Sebastian Huber 
> >>  wrote:
> >>
> >>
> >> 1. Should we use one shared glossary which is included in all documents?
> >>
> >> 2. Do we want to use document-specific glossaries and maintain 
> >> copy-and-paste entries by hand?
> >>
> >> With option 1. the glossary may contain a lot of things which are 
> >> unrelated to a specific document. However, if the Sphinx glossary support 
> >> gets improved, this problem may vanish. With 2. we have a maintenance 
> >> problem, e.g. keeping the copy and paste definitions in synchronization.
> >>
> >> What do you think?
> >>
> >
> > Can we fuse 1+2 - keep a single (master) glossary file with added tags 
> > "glos1", "glos2" (or whatever)
> > We then have a script that generates the different glossaries from that one 
> > master?
> >
> > I guess the issue is how easy it is to run that script from within the 
> > various document build workflows.
>
> Yes, we can also add our own scripts to automate this. The question is
> if we want to develop special case solutions or try to fix it in the
> upstream Sphinx project. Using our own scripts would be much probably
> much easier, unless someone is familiar with the Sphinx internals.
>
> We could for example get the terms used in a document and based on this
> generate a document-specific glossary from a master template, e.g.
>
> grep -r --include='*.rst' ':term:`[^`]*`' -o
> eng/req-eng.rst::term:`GNAT`
> eng/req-eng.rst::term:`EARS`
> eng/req-eng.rst::term:`API`
> eng/req-eng.rst::term:`ABI`
> eng/req-eng.rst::term:`source code`
> eng/req-eng.rst::term:`CCB`
> eng/req-eng.rst::term:`ISVV`
> eng/req-eng.rst::term:`ReqIF`
> eng/req-eng.rst::term:`Doorstop`
> eng/req-eng.rst::term:`Doorstop`
> eng/req-eng.rst::term:`YAML`
> c-user/key_concepts.rst::term:`thread`
> c-user/symmetric_multiprocessing_services.rst::term:`TLS`
> c-user/symmetric_multiprocessing_services.rst::term:`C11`
> c-user/symmetric_multiprocessing_services.rst::term:`MCS`
> c-user/symmetric_multiprocessing_services.rst::term:`FIFO`
> c-user/symmetric_multiprocessing_services.rst::term:`NUMA`
> c-user/symmetric_multiprocessing_services.rst::term:`TCB`
> c-user/symmetric_multiprocessing_services.rst::term:`TTAS`
> c-user/glossary.rst::term:`C11`
> c-user/glossary.rst::term:`C11`
> c-user/glossary.rst::term:`C++11`
> user/start/prefixes.rst::term:`prefix`
> user/installation/project-sandboxing.rst::term:`prefix`
> user/overview/index.rst::term:`RTEMS`
> user/overview/index.rst::term:`SMP`
> user/overview/index.rst::term:`APIs `
> user/overview/index.rst::term:`POSIX`
> user/overview/index.rst::term:`C11`
> user/overview/index.rst::term:`C++11`
> user/overview/index.rst::term:`GCC`
> user/overview/index.rst::term:`EMB²`
> user/overview/index.rst::term:`OpenMP`
> user/overview/index.rst::term:`Futex`
> user/overview/index.rst::term:`OpenMP`
> user/overview/index.rst::term:`OMIP`
> user/overview/index.rst::term:`MrsP`
> user/overview/index.rst::term:`TLS`
> user/overview/index.rst::term:`EDF`
> user/overview/index.rst::term:`EDF`
> user/overview/index.rst::term:`APA`
> user/overview/index.rst::term:`IMFS`
> user/overview/index.rst::term:`FAT`
> user/overview/index.rst::term:`RFS`
> user/overview/index.rst::term:`NFSv2`
> user/overview/index.rst::term:`JFFS2`
> user/overview/index.rst::term:`YAFFS2`
> user/hardware/architectures.rst::term:`ABI`
> eclipse/overview.rst::term:`RTEMS`
>
> An include if used policy is not followed by the Classic API Guide since
> this feature was not available in the old texinfo framework as well.
>

I prefer we use a centralized glossary/document to generate individual
glossaries (via scripting or improving Sphinx). This will be a lot
easier to maintain.

> --
> Sebastian Huber, embedded brains GmbH
>
> Address : Dornierstr. 4, D-82178 Puchheim, Germany
> Phone   : +49 89 189 47 41-16
> Fax : +49 89 189 47 41-09
> E-Mail  : sebastian.hu...@embedded-brains.de
> PGP : Public key available on request.
>
> Diese Nachricht ist keine geschäftliche Mitteilung im Sinne des EHUG.
> ___
> devel mailing list
> devel@rtems.org
> http://lists.rtems.org/mailman/listinfo/devel
___
devel mailing list
devel@rtems.org
http://lists.rtems.org/mailman/listinfo/devel

Re: Glossary of Terms

[Sebastian Huber]

On 03/01/2020 10:42, andrew.butterfi...@cs.tcd.ie wrote:

Hello all, and Happy New Year!


On 3 Jan 2020, at 08:10, Sebastian Huber  
wrote:


1. Should we use one shared glossary which is included in all documents?

2. Do we want to use document-specific glossaries and maintain copy-and-paste 
entries by hand?

With option 1. the glossary may contain a lot of things which are unrelated to 
a specific document. However, if the Sphinx glossary support gets improved, 
this problem may vanish. With 2. we have a maintenance problem, e.g. keeping 
the copy and paste definitions in synchronization.

What do you think?



Can we fuse 1+2 - keep a single (master) glossary file with added tags "glos1", 
"glos2" (or whatever)
We then have a script that generates the different glossaries from that one 
master?

I guess the issue is how easy it is to run that script from within the various 
document build workflows.


Yes, we can also add our own scripts to automate this. The question is 
if we want to develop special case solutions or try to fix it in the 
upstream Sphinx project. Using our own scripts would be much probably 
much easier, unless someone is familiar with the Sphinx internals.


We could for example get the terms used in a document and based on this 
generate a document-specific glossary from a master template, e.g.


grep -r --include='*.rst' ':term:`[^`]*`' -o
eng/req-eng.rst::term:`GNAT`
eng/req-eng.rst::term:`EARS`
eng/req-eng.rst::term:`API`
eng/req-eng.rst::term:`ABI`
eng/req-eng.rst::term:`source code`
eng/req-eng.rst::term:`CCB`
eng/req-eng.rst::term:`ISVV`
eng/req-eng.rst::term:`ReqIF`
eng/req-eng.rst::term:`Doorstop`
eng/req-eng.rst::term:`Doorstop`
eng/req-eng.rst::term:`YAML`
c-user/key_concepts.rst::term:`thread`
c-user/symmetric_multiprocessing_services.rst::term:`TLS`
c-user/symmetric_multiprocessing_services.rst::term:`C11`
c-user/symmetric_multiprocessing_services.rst::term:`MCS`
c-user/symmetric_multiprocessing_services.rst::term:`FIFO`
c-user/symmetric_multiprocessing_services.rst::term:`NUMA`
c-user/symmetric_multiprocessing_services.rst::term:`TCB`
c-user/symmetric_multiprocessing_services.rst::term:`TTAS`
c-user/glossary.rst::term:`C11`
c-user/glossary.rst::term:`C11`
c-user/glossary.rst::term:`C++11`
user/start/prefixes.rst::term:`prefix`
user/installation/project-sandboxing.rst::term:`prefix`
user/overview/index.rst::term:`RTEMS`
user/overview/index.rst::term:`SMP`
user/overview/index.rst::term:`APIs `
user/overview/index.rst::term:`POSIX`
user/overview/index.rst::term:`C11`
user/overview/index.rst::term:`C++11`
user/overview/index.rst::term:`GCC`
user/overview/index.rst::term:`EMB²`
user/overview/index.rst::term:`OpenMP`
user/overview/index.rst::term:`Futex`
user/overview/index.rst::term:`OpenMP`
user/overview/index.rst::term:`OMIP`
user/overview/index.rst::term:`MrsP`
user/overview/index.rst::term:`TLS`
user/overview/index.rst::term:`EDF`
user/overview/index.rst::term:`EDF`
user/overview/index.rst::term:`APA`
user/overview/index.rst::term:`IMFS`
user/overview/index.rst::term:`FAT`
user/overview/index.rst::term:`RFS`
user/overview/index.rst::term:`NFSv2`
user/overview/index.rst::term:`JFFS2`
user/overview/index.rst::term:`YAFFS2`
user/hardware/architectures.rst::term:`ABI`
eclipse/overview.rst::term:`RTEMS`

An include if used policy is not followed by the Classic API Guide since 
this feature was not available in the old texinfo framework as well.


--
Sebastian Huber, embedded brains GmbH

Address : Dornierstr. 4, D-82178 Puchheim, Germany
Phone   : +49 89 189 47 41-16
Fax : +49 89 189 47 41-09
E-Mail  : sebastian.hu...@embedded-brains.de
PGP : Public key available on request.

Diese Nachricht ist keine geschäftliche Mitteilung im Sinne des EHUG.
___
devel mailing list
devel@rtems.org
http://lists.rtems.org/mailman/listinfo/devel

Glossary of Terms

[Sebastian Huber]

Hello,

we have currently only two glossary of terms in the RTEMS documentation set:

https://docs.rtems.org/branches/master/user/glossary/index.html

https://docs.rtems.org/branches/master/c-user/glossary.html

We also need one in the RTEMS Software Engineering manual. Sphinx has 
currently some limitations in the way glossary terms are managed:


https://github.com/sphinx-doc/sphinx/issues/3559

It would be nice if it worked like the TeX acronym package:

https://ctan.org/pkg/acronym?lang=en

The problem is that the Sphinx maintainer is not really interested in 
this feature and I don't have enough knowledge/time/skill to implement 
it myself.


How do we want to deal with glossaries in the documentation?

1. Should we use one shared glossary which is included in all documents?

2. Do we want to use document-specific glossaries and maintain 
copy-and-paste entries by hand?


With option 1. the glossary may contain a lot of things which are 
unrelated to a specific document. However, if the Sphinx glossary 
support gets improved, this problem may vanish. With 2. we have a 
maintenance problem, e.g. keeping the copy and paste definitions in 
synchronization.


What do you think?

A proper glossary is very important from my point of view, especially 
for the pre-qualification activity. Different standards define terms 
differently. We need a clear definition of terms for the RTEMS Project, 
otherwise the will have a lot of confusion if people from different 
domains task with each other.


--
Sebastian Huber, embedded brains GmbH

Address : Dornierstr. 4, D-82178 Puchheim, Germany
Phone   : +49 89 189 47 41-16
Fax : +49 89 189 47 41-09
E-Mail  : sebastian.hu...@embedded-brains.de
PGP : Public key available on request.

Diese Nachricht ist keine geschäftliche Mitteilung im Sinne des EHUG.
___
devel mailing list
devel@rtems.org
http://lists.rtems.org/mailman/listinfo/devel