Version-adaptive documentation: Difference between revisions

From GNU Radio
Jump to navigation Jump to search
(add test results)
 
(18 intermediate revisions by the same user not shown)
Line 11: Line 11:
* Create a test page with sections which can be hidden, based on a 'data-vad' attribute.
* Create a test page with sections which can be hidden, based on a 'data-vad' attribute.
* Create a form to enter a Version selection.
* Create a form to enter a Version selection.
* Store the Version selection in a user cookie.
* Before displaying the page, execute a script to show or hide sections based on the Version selection.
* Before displaying the page, execute a script to show or hide sections relevant to the Version selection.


<h4>Test results</h4>
<h4>Test results</h4>
----
----
<p>All versions selected.</p>
<p>Page before any selections are made (i.e. all information is shown).</p>
[[File:Phase1_all.png|326px]]
[[File:Phase1_all.png|499px]]
----
----
<p>Version 3.9 selected.</p>
<p>Version selection before clicking 'Submit'.</p>
[[File:Phase1_3-9.png|329px]]
[[File:Gr_version_select.png|491px]]
----
<p>Version 3.9 selected. Note that the items for 3.8 are not shown (hidden).</p>
[[File:Phase1_3-9.png|494px]]
----
<h4>Conclusions</h4>
# I have found that this methodology for hiding sections of a document is relatively easy.
# There are several groups of pages which might benefit from this method:
## Block docs
## Tutorials
## Installation instructions
# Specific examples are:
## [[Message_Debug]]
## [[Packet_Communications]]
## [[LinuxInstall]]
 
<h3>Phase 2</h3>
 
<h4>Plan</h4>
 
* Use a 'test' MediaWiki.
* Put a version selection menu below the "Tools" group in the left-hand Navigation section.
* Create a test page with HTML "div" tags which can be hidden, based on a 'data-vad' attribute.
* Embed a JavaScript link at the end of the page HTML to perform the requested selection.
 
<h4>Test results</h4>
----
<p>Page before any selections are made (i.e. all information is shown).</p>
[[File:Phase2_all.png|800px]]
----
<p>Version 3.9 selected. Note that the items for 3.8 are not shown (hidden).</p>
[[File:Phase2_3-9.png|800px]]
----
 
<h4>Conclusions</h4>
# Testing with the [[Message_Debug_Test_Page]] proves the basic concept.
# You can select multiple versions such as 3.9 and 3.10, but there are no smarts to know that the 3.9 content applies to 3.10, so selecting 3.10 only yields no content.
# Version 4.0 can be added whenever we want.
# Additional work would need to be done in order to change the Table of Contents based on the version selection.
 
<h3>Phase 3</h3>
 
<h4>Plan</h4>
 
* Revise [[Message_Debug_Test_Page]] to show version 3.10 properly
* Make a test version of [[Packet_Communications]]
 
== How to mark up a MediaWiki doc for Version-adaptive documentation ==
 
* Open the document to Edit
* Enter the first three lines as follows:
<pre>
__NOTOC__
<span id="gr_vad"></span>
<hr>
</pre>
 
* For each section of content which applies specifically to one or more GNU Radio versions, surround it with
<pre>
<div data-vad="3.9">
</pre>
(using the applicable version or comma separated versions) and
 
<pre>
</div>
</pre>
A section can include any amount of headings, paragraphs, and other content.
 
* Keep in mind that the majority of a document will apply to all versions, and therefore does not need <b><u>any</u></b> version-related markup.
 
* Here is an example taken from [[Message_Debug]]:
<pre>
<div data-vad="3.9,3.10">
==== Versions 3.9 and 3.10 ====
----
; print
: Prints all messages to standard out. If the message is a PDU, it will receive special formatting and the <code>PDU Vectors</code> block parameter will determine if the uniform vector is printed or not.
; store
: Stores the message in an internal vector. It works in conjunction with a message_debug::get_message(size_t i) call that allows us to retrieve message i afterward.
; print_pdu
: PDU messages are redirected to the <code>print</code> port. This is included for compatibility and is no longer recommended for use.
</div>
</pre>
 
* Add a last line:
<pre>
[[Category:Version-adaptive docs]]
</pre>
There may be another Category as well, such as 'Category:Block Docs' or 'Category:Tutorials'. Put each one on a separate line.
 
== Lessons learned using JavaScript in MediaWiki:Common.js ==
* The JavaScript <b>must</b> conform to ECMAScript 2009, also known as ES5.
* The script is triggered by MediaWiki, so no additional trigger is needed (such as document.body.onload).
* The content is inserted at the end of every page and is wrapped in <code><script></code> and <code></script></code> tags by MediaWiki.
* Careful consideration must be given to avoid affecting unintended MediaWiki pages.
 
== References ==
* [https://github.com/duggabe/js-vad Using JavaScript to modify MediaWiki pages]

Latest revision as of 14:17, 28 December 2022

Concept

I am looking into the possibility of making certain pages of our Wiki be adaptive to the user's GNU Radio version (or desired version) so that sections which don't apply would be hidden. This would make cleaner page presentations and reduce the clutter of unrelated information.

Proof of Concept

Phase 1

Plan

  • Emulate MediaWiki with a local nodeJS program to allow non-destructive testing.
  • Create a test page with sections which can be hidden, based on a 'data-vad' attribute.
  • Create a form to enter a Version selection.
  • Before displaying the page, execute a script to show or hide sections based on the Version selection.

Test results


Page before any selections are made (i.e. all information is shown).

Phase1 all.png


Version selection before clicking 'Submit'.

Gr version select.png


Version 3.9 selected. Note that the items for 3.8 are not shown (hidden).

Phase1 3-9.png


Conclusions

  1. I have found that this methodology for hiding sections of a document is relatively easy.
  2. There are several groups of pages which might benefit from this method:
    1. Block docs
    2. Tutorials
    3. Installation instructions
  3. Specific examples are:
    1. Message_Debug
    2. Packet_Communications
    3. LinuxInstall

Phase 2

Plan

  • Use a 'test' MediaWiki.
  • Put a version selection menu below the "Tools" group in the left-hand Navigation section.
  • Create a test page with HTML "div" tags which can be hidden, based on a 'data-vad' attribute.
  • Embed a JavaScript link at the end of the page HTML to perform the requested selection.

Test results


Page before any selections are made (i.e. all information is shown).

Phase2 all.png


Version 3.9 selected. Note that the items for 3.8 are not shown (hidden).

Phase2 3-9.png


Conclusions

  1. Testing with the Message_Debug_Test_Page proves the basic concept.
  2. You can select multiple versions such as 3.9 and 3.10, but there are no smarts to know that the 3.9 content applies to 3.10, so selecting 3.10 only yields no content.
  3. Version 4.0 can be added whenever we want.
  4. Additional work would need to be done in order to change the Table of Contents based on the version selection.

Phase 3

Plan

How to mark up a MediaWiki doc for Version-adaptive documentation

  • Open the document to Edit
  • Enter the first three lines as follows:
__NOTOC__
<span id="gr_vad"></span>
<hr>
  • For each section of content which applies specifically to one or more GNU Radio versions, surround it with
<div data-vad="3.9">

(using the applicable version or comma separated versions) and

</div>

A section can include any amount of headings, paragraphs, and other content.

  • Keep in mind that the majority of a document will apply to all versions, and therefore does not need any version-related markup.
<div data-vad="3.9,3.10">
==== Versions 3.9 and 3.10 ====
----
; print
: Prints all messages to standard out. If the message is a PDU, it will receive special formatting and the <code>PDU Vectors</code> block parameter will determine if the uniform vector is printed or not.
; store
: Stores the message in an internal vector. It works in conjunction with a message_debug::get_message(size_t i) call that allows us to retrieve message i afterward.
; print_pdu
: PDU messages are redirected to the <code>print</code> port. This is included for compatibility and is no longer recommended for use.
</div>
  • Add a last line:
[[Category:Version-adaptive docs]]

There may be another Category as well, such as 'Category:Block Docs' or 'Category:Tutorials'. Put each one on a separate line.

Lessons learned using JavaScript in MediaWiki:Common.js

  • The JavaScript must conform to ECMAScript 2009, also known as ES5.
  • The script is triggered by MediaWiki, so no additional trigger is needed (such as document.body.onload).
  • The content is inserted at the end of every page and is wrapped in <script> and </script> tags by MediaWiki.
  • Careful consideration must be given to avoid affecting unintended MediaWiki pages.

References