Merge branch 'comment-parts-not-to-display' into 'main'

20240701_faq.md: Comment top level parts that should not be displayed

See merge request !1

20240701_faq.md

+
+<!---
+
+This is commented because the FAQ page on SWH WordPress website is
+dynamically generated from this markdown document and this should
+not be displayed.
+
+After each document update in this git repository, the FAQ page is
+automatically updated on the WordPress website.
+
 ---
 tags: documentation, ambassadors
 ---
-Why this new version? 
-Slight changes have to be made. 
+Why this new version?
+Slight changes have to be made.
 
-See questions in: 
+See questions in:
 https://hedgedoc.softwareheritage.org/6hFGAHdUTY2wWKr5OqwzkQ?both#
 
 
 # FAQ Software Heritage (website)
 
-## 1. General 
+--->
+
+## 1. General
 
 ### 1.1 What is Software Heritage?
 
@@ -28,7 +40,7 @@ For more information about the Software Heritage [mission](https://www.softwareh
 
 ### 1.2 What is the Software Heritage archive?
 
-The Software Heritage archive is the largest public collection of source code in existence. Visit the archive on https://archive.softwareheritage.org. 
+The Software Heritage archive is the largest public collection of source code in existence. Visit the archive on https://archive.softwareheritage.org.
 
 ### 1.3 What is the size of the archive?
 The archive is growing over time as we crawl new source code from software projects and development forges. You can see live counters of the archive contents, as well as a breakdown by crawled origins, on  https://archive.softwareheritage.org.
@@ -62,7 +74,7 @@ Here is an excerpt of this list:
 
 ### 2.2 If my code is on GitHub/GitLab/Bitbucket, is it already archived in Software Heritage?
 
-It might be, as we crawl these and other popular forges regularly. 
+It might be, as we crawl these and other popular forges regularly.
 Search for your code repository on https://archive.softwareheritage.org/browse/search/.
 
 <details>
@@ -73,7 +85,7 @@ If it is not there yet, or if the latest snapshot is not the most recent state o
 https://archive.softwareheritage.org/save/ or by clicking on the "Save again" button in the browse view.
 
 ![](https://hedgedoc.softwareheritage.org/uploads/upload_f927d52a90509ceae1f6bd595ace41a2.png)
-    
+
 A [GitHub action](https://github.com/marketplace/actions/save-to-software-heritage) is available to automatically push a save code now request. Here is an [example](https://github.com/patrickfuchs/buildH/blob/master/.github/workflows/archive-to-software-heritage.yml) of this action configured to run each time a new release is issued.
 
 You can also use the [browser extension](https://www.softwareheritage.org/2022/08/02/updateswh-browser-extension/).
@@ -91,7 +103,7 @@ We do not inspect or filter the source code, and archive anything that we can ge
 <summary> Expand for details </summary>
 <br>
 
-The reason for this approach is because the value of software source code cannot be known in advance. When a project starts, one cannot predict whether it will become a key software component or not. For example, when [Rasmus Lerdorf](https://fr.wikipedia.org/wiki/Rasmus_Lerdorf) released [the first version on PHP back in 1995](https://groups.google.com/g/comp.infosystems.www.authoring.cgi/c/PyJ25gZ6z7A/m/M9FkTUVDfcwJ), who could have predicted that it would become one of the most popular tools for the Web. 
+The reason for this approach is because the value of software source code cannot be known in advance. When a project starts, one cannot predict whether it will become a key software component or not. For example, when [Rasmus Lerdorf](https://fr.wikipedia.org/wiki/Rasmus_Lerdorf) released [the first version on PHP back in 1995](https://groups.google.com/g/comp.infosystems.www.authoring.cgi/c/PyJ25gZ6z7A/m/M9FkTUVDfcwJ), who could have predicted that it would become one of the most popular tools for the Web.
 
 <figure>
 <img src="https://imgs.xkcd.com/comics/dependency.png">
@@ -101,7 +113,7 @@ XKCD Comics https://xkcd.com/2347/ (CC BY-NC 2.5)
 </figcaption>
 </figure>
 
-And it also happens that [very precious pieces of source code may be go unnoticed for decades](https://en.wikipedia.org/wiki/OpenSSL), until one day [some unexpected bug unveils that a big part of our digital infrastructure relies on them](https://en.wikipedia.org/wiki/Heartbleed). 
+And it also happens that [very precious pieces of source code may be go unnoticed for decades](https://en.wikipedia.org/wiki/OpenSSL), until one day [some unexpected bug unveils that a big part of our digital infrastructure relies on them](https://en.wikipedia.org/wiki/Heartbleed).
 
 </details>
 
@@ -120,8 +132,8 @@ Our core mission is to preserve source code, because it is human readable and co
 
 ### 2.7 I can't find all my "releases" in a git repository in Software Heritage, what should I do?
 
-Do not worry, your repository has been saved in full. 
-What you are witnessing is just a terminological difference between what 
+Do not worry, your repository has been saved in full.
+What you are witnessing is just a terminological difference between what
 platforms like GitHub calls "releases" (any non annotated git tag) and what we call "releases" (a node in the Merkle tree, which corresponds to a git annotated tag). This is a common issue, as you can see for example in [this discussion thread](https://stackoverflow.com/questions/11514075/what-is-the-difference-between-an-annotated-and-unannotated-tag).
 
 <details>
@@ -223,7 +235,7 @@ Notice that the Permalinks tab offers a plurality of options to pick a SWHID (yo
 ![](https://annex.softwareheritage.org/public/tutorials/getswhid_snippet.gif)
 </details>
 
-### 3.4 Which type of SWHID should I use in my article/documentation? 
+### 3.4 Which type of SWHID should I use in my article/documentation?
 
 
 It really depends on your use case, but as a general suggestion we recommend to take *the full SWHID of a directory (with the contextual information)*.
@@ -234,7 +246,7 @@ It really depends on your use case, but as a general suggestion we recommend to
 
 When writing a research article, a blog post or technical documentation, one may face some tension between the need to provide the maximum amount of information, using the full SWHID, or keeping the reference short (for example due to page limitations).
 
-Here is the recommended best practice to address this issue: 
+Here is the recommended best practice to address this issue:
 1) get the full SWHID for the 'directory' containing the version of the code you want to reference. Here is an example of such a full SWHID:
  `swh:1:dir:013573086777370b558b1a9ecb6d0dca9bb8ea18;origin=https://gitlab.com/lemta-rheosol/craft-virtual-dma;visit=swh:1:snp:ef1a939275f05b667e189afbeed5fd59cca51c9d;anchor=swh:1:rev:ad74f6a7f73c7906f9b36ee28dd006231f42552e`
 
@@ -244,7 +256,7 @@ This effect can be achieved as follows in LaTeX:
 
 ```\href{https://archive.softwareheritage.org/swh:1:dir:013573086777370b558b1a9ecb6d0dca9bb8ea18;origin=https://gitlab.com/lemta-rheosol/craft-virtual-dma;visit=swh:1:snp:ef1a939275f05b667e189afbeed5fd59cca51c9d;anchor=swh:1:rev:ad74f6a7f73c7906f9b36ee28dd006231f42552e/}{swh:1:dir:013573086777370b558b1a9ecb6d0dca9bb8ea18}```
 
-or in Markdown: 
+or in Markdown:
 
 ```[swh:1:dir:013573086777370b558b1a9ecb6d0dca9bb8ea18](https://archive.softwareheritage.org/swh:1:dir:013573086777370b558b1a9ecb6d0dca9bb8ea18;origin=https://gitlab.com/lemta-rheosol/craft-virtual-dma;visit=swh:1:snp:ef1a939275f05b667e189afbeed5fd59cca51c9d;anchor=swh:1:rev:ad74f6a7f73c7906f9b36ee28dd006231f42552e/)```
 
@@ -257,7 +269,7 @@ In the digital version *the clickable link* uses *the full SWHID* to let the rea
 
 If your code (or the latest version of it) is not yet in the archive, you need first to trigger its archival. This can be done with a ["Save Code Now"](https://save.softwareheritage.org) request, or via the deposit API.
 
-Once a Save Code Now request is issued, the ingestion of the code is usually completed in a few minutes, depending on the size of the repository. Once it's done, the status of the save request is updated and you can get the SWHID as shown before. 
+Once a Save Code Now request is issued, the ingestion of the code is usually completed in a few minutes, depending on the size of the repository. Once it's done, the status of the save request is updated and you can get the SWHID as shown before.
 
 When a deposit is submitted, the ingestion is also usually completed in a few minutes and the SWHID is accessible through the SWORD status response.
 
@@ -284,7 +296,7 @@ Please do not clone a full repository directly from Software Heritage: it is an
 <summary> Expand for details </summary>
 <br>
 
-Software Heritage stores all the software artifacts in a massive shared [Merkle tree](https://en.wikipedia.org/wiki/Merkle_tree), so that exporting (a specific version of) an archived respository implies traversing the graph to get all the relevant contents and packaging them up for your consumption. This operation is much more expensive than downloading an existing tar file or cloning a repository from a forge. 
+Software Heritage stores all the software artifacts in a massive shared [Merkle tree](https://en.wikipedia.org/wiki/Merkle_tree), so that exporting (a specific version of) an archived respository implies traversing the graph to get all the relevant contents and packaging them up for your consumption. This operation is much more expensive than downloading an existing tar file or cloning a repository from a forge.
 
 If really Software Heritage is your last resort, and you cannot find the source code of interest elsewhere, we recommend that you download only the version of interest for you, using the "*directory*" option of the Download button that you find when you browse the archive.
 
@@ -360,7 +372,7 @@ Last but not least, [Software Heritage indexes](https://www.softwareheritage.org
 <figure>
 <img src="https://hedgedoc.softwareheritage.org/uploads/upload_ef853cffeee220220c6e12a7ba0c40db.png">
 <figcaption>
-    
+
 Credit: Gruenpeter M. and Thornton K. (2018) Pathways for Discovery of Free Software (slide deck from LibrePlanet 2018). https://en.wikipedia.org/wiki/File:Pathways-discovery-free.pdf
 </figcaption>
 </figure>

README.md

 # Software Heritage's FAQ repository
 
-This repository is dedicated to writing the collection of Frequently Asked Questions. 
+This repository is dedicated to writing the collection of Frequently Asked Questions.
 Ambassadors and contributors can do MR or add issues dedicated to the FAQ.
 - the faq.md file can be easily exported into html with the correct tags per question
 - concerning the devs/users/sys-admins FAQ, they will be directly edited in the docs
@@ -11,5 +11,8 @@ We have now a significant amount of material from interviews, newspaper articles
 From this material, we compiled a list of frequently asked questions with the typical answers we provide.
 E.g.: what is software source code? why archiving software source code? how do you decide what to archive? do you also archive binaries? hey, the Library of Alexandria went up in flames, how do you plan to avoid this happening to you? etc. etc.
 
-The full FAQ is available on faq.md, section 1 to 5 are already online on https://www.softwareheritage.org/faq/.
+The full FAQ, with some unpublished content waiting for review, is available on [faq.md](faq.md) while the published FAQ is available on [20240701_faq.md](20240701_faq.md), section 1 to 5 are already online on https://www.softwareheritage.org/faq/.
 
+The content of each FAQ page (one per supported language) located at https://www.softwareheritage.org/faq/ is dynamically generated from associated markdown file in that repository, every change pushed to is automatically taken into account when refreshing the published FAQ page.
+
+To be noted, for a proper display of a FAQ page in the main Software Heritage website, the associated markdown document should start with a level 2 heading (`## section title`).
\ No newline at end of file