# Starting the fpm user documentation **URL:** \ **Category:** Announcements\ **Created:** [November 26, 2021, 1:55pm UTC](https://fortran-lang.discourse.group/t/starting-the-fpm-user-documentation/2338 "2021-11-26T13:55:37Z")\ **Posts on this page:** 20\ **Page:** 1
**Author:** ![awvwgk](https://yyz2.discourse-cdn.com/free1/user_avatar/fortran-lang.discourse.group/awvwgk/32/154_2.png) [@awvwgk](https://fortran-lang.discourse.group/u/awvwgk)\ **Post date:** [November 26, 2021, 1:55pm UTC](https://fortran-lang.discourse.group/t/starting-the-fpm-user-documentation/2338/1 "2021-11-26T13:55:37Z")
I started working on a page for the fpm user documentation. There is a lot of work that still needs to be done and various details that must be figured out, but the general structure is already in place: 1. four main parts of documentation: _tutorials_, _recipes_, _design_ and _references_. 2. multilingual support (English and a partial German translation) 3. a news section to announce new releases, conference talks and new packages The repository can be found here > **[GitHub - awvwgk/fpm-docs: (Unofficial) documentation repository for the...](https://github.com/awvwgk/fpm-docs)** > > (Unofficial) documentation repository for the Fortran package manager (fpm) - GitHub - awvwgk/fpm-docs: (Unofficial) documentation repository for the Fortran package manager (fpm) I also put up a [preview](https://awvwgk.github.io/fpm-docs/index.html). I’m building with _sphinx_ and _myst-markdown_, all you need to get started is actually a conda installation: ```nohighlight conda env create -n sphinx -f environment.yaml conda activate sphinx ``` Help is very welcome, feel free to contribute tutorials or recipes, help us formulate the design principles behind fpm or improve the references and specifications. Also, we can translate the docs 🎉. If you would like to contribute a translation, just search for the `de` identifiers in the `Makefile` and the `pages/conf.py` to add a new language and run ```nohighlight make gettext ``` The _po_ files will appear in the `locale/` directory and you can start translating! ---
**Author:** ![alozada](https://yyz2.discourse-cdn.com/free1/user_avatar/fortran-lang.discourse.group/alozada/32/298_2.png) [@alozada](https://fortran-lang.discourse.group/u/alozada)\ **Post date:** [November 26, 2021, 2:31pm UTC](https://fortran-lang.discourse.group/t/starting-the-fpm-user-documentation/2338/2 "2021-11-26T14:31:09Z")
I can help with translations to Spanish, if there is interest in that. ---
**Author:** ![Beliavsky](https://avatars.discourse-cdn.com/v4/letter/b/ba8739/32.png) [@Beliavsky](https://fortran-lang.discourse.group/u/Beliavsky)\ **Post date:** [November 26, 2021, 2:35pm UTC](https://fortran-lang.discourse.group/t/starting-the-fpm-user-documentation/2338/3 "2021-11-26T14:35:32Z")
@tomohirodegawa has just created [Examples of Fortran-stdlib](https://github.com/degawa/ex_stdlib). The readme.md is in Japanese, and Google Translate in Chrome can nicely render it in English. Someone could fork it and create an English version. ---
**Author:** ![awvwgk](https://yyz2.discourse-cdn.com/free1/user_avatar/fortran-lang.discourse.group/awvwgk/32/154_2.png) [@awvwgk](https://fortran-lang.discourse.group/u/awvwgk)\ **Post date:** [November 26, 2021, 4:13pm UTC](https://fortran-lang.discourse.group/t/starting-the-fpm-user-documentation/2338/4 "2021-11-26T16:13:57Z")
> [@alozada](#): > > I can help with translations to Spanish, if there is interest in that. You are very welcome, thanks. I invited you to the repository as collaborator, this should allow you to manage issues. I opened an issue for a Spanish translation as well, anyone is of course welcome to join this effort. > > > See \[Commits\](/awvwgk/fpm-docs/pull/4/commits) and \[Changes\](/awvwgk/fpm-docs/pu…ll/4/files) for more details. > > \----- > Created by \[\ \*\*pull\[bot\]\*\*\](https://github.com/wei/pull) > > \_Can you help keep this open source service alive? \*\*\[💖 Please sponsor : )\](https://prod.download/pull-pr-sponsor)\*\*\_ I don’t speak Spanish, so I won’t be of much help here, other than helping with the technical details. ---
**Author:** ![Beliavsky](https://avatars.discourse-cdn.com/v4/letter/b/ba8739/32.png) [@Beliavsky](https://fortran-lang.discourse.group/u/Beliavsky)\ **Post date:** [November 28, 2021, 12:52pm UTC](https://fortran-lang.discourse.group/t/starting-the-fpm-user-documentation/2338/5 "2021-11-28T12:52:27Z")
> [@awvwgk](#): > > I started working on a page for the fpm user documentation. There is a lot of work that still needs to be done and various details that must be figured out, but the general structure is already in place: > > 1. four main parts of documentation: _tutorials_, _recipes_, _design_ and _references_. A fifth part could be added: _discussions_. Most code in stdlib has one or more related [issues](https://github.com/fortran-lang/stdlib/issues) where it has been discussed. If related discussions were listed for each source file, that would help to fill in the reference information, since people have often provided links to references when discussing algorithms. Reading discussions could also tell users why algorithms were chosen and what the alternatives are. ---
**Author:** ![awvwgk](https://yyz2.discourse-cdn.com/free1/user_avatar/fortran-lang.discourse.group/awvwgk/32/154_2.png) [@awvwgk](https://fortran-lang.discourse.group/u/awvwgk)\ **Post date:** [November 28, 2021, 2:33pm UTC](https://fortran-lang.discourse.group/t/starting-the-fpm-user-documentation/2338/6 "2021-11-28T14:33:42Z")
Discussion fit well in the existing categories, they would be part of the design documents for explaining the background of the respective parts of fpm. I’m also planning to have some meta-documentation on the docs themselves to clarify points like this, see > > > The documentation follows the Diátaxis framework (https://diataxis.fr/). A short… overview in the design section should be added to clarify the four sections the documentation is subdivided in. Thanks to Vincent @vmagnin for bring this framework to my attention. ---
**Author:** ![certik](https://yyz2.discourse-cdn.com/free1/user_avatar/fortran-lang.discourse.group/certik/32/4_2.png) [@certik](https://fortran-lang.discourse.group/u/certik)\ **Post date:** [November 28, 2021, 4:35pm UTC](https://fortran-lang.discourse.group/t/starting-the-fpm-user-documentation/2338/7 "2021-11-28T16:35:18Z")
> [@Beliavsky](#): > > A fifth part could be added: _discussions_ . Most code in stdlib has one or more related [issues](https://github.com/fortran-lang/stdlib/issues) where it has been discussed. If related discussions were listed for each source file, that would help to fill in the reference information, since people have often provided links to references when discussing algorithms. Reading discussions could also tell users why algorithms were chosen and what the alternatives are. Excellent idea. Indeed, we should link all discussions for each module in stdlib. I think the discussions are usually related to the whole module, not just a single file. It’s the same idea behind the [GitHub - j3-fortran/fortran\_proposals: Proposals for the Fortran Standard Committee](https://github.com/j3-fortran/fortran_proposals/) repository: to be able to track discussions behind each Fortran feature as it is added to the standard, and features that didn’t make it (and why). ---
**Author:** ![awvwgk](https://yyz2.discourse-cdn.com/free1/user_avatar/fortran-lang.discourse.group/awvwgk/32/154_2.png) [@awvwgk](https://fortran-lang.discourse.group/u/awvwgk)\ **Post date:** [December 12, 2021, 11:01am UTC](https://fortran-lang.discourse.group/t/starting-the-fpm-user-documentation/2338/8 "2021-12-12T11:01:29Z")
I updated the documentation with a tutorial for using dependencies in fpm: [Adding dependencies — Fortran package manager](https://awvwgk.github.io/fpm-docs/en/tutorial/dependencies.html). Feedback is very welcome. Also, I’m looking for other tutorial and how-to ideas (maybe we can do a tutorial using [fftpack](https://github.com/fortran-lang/fftpack)?). * * * Thanks to @zoziha and @alozada we now have also multilingual fpm documentation. Most pages are available in Chinese, Spanish and German. Let us know how good we are doing with those translations, at least for me writing technical documentation in German is kind of a new thing 😅 While building up the pages we stumbled upon a couple of issues with the framework we are using - [i18n: inconsistent localization for Chinese (zh\_CN vs zh-cn) · Issue #433 · executablebooks/sphinx-book-theme · GitHub](https://github.com/executablebooks/sphinx-book-theme/issues/433) - [i18n: card title is not captured in po-file for translation · Issue #45 · executablebooks/sphinx-design · GitHub](https://github.com/executablebooks/sphinx-design/issues/45) - [i18n: translating buttom-ref label results in loss of CSS classes · Issue #44 · executablebooks/sphinx-design · GitHub](https://github.com/executablebooks/sphinx-design/issues/44) I hope we can contribute fixes to the upstream projects, but unfortunately they were not really responsive yet. ---
**Author:** ![urbanjost](https://avatars.discourse-cdn.com/v4/letter/u/0ea827/32.png) [@urbanjost](https://fortran-lang.discourse.group/u/urbanjost)\ **Post date:** [December 12, 2021, 3:35pm UTC](https://fortran-lang.discourse.group/t/starting-the-fpm-user-documentation/2338/9 "2021-12-12T15:35:06Z")
Nice. In the section on dependencies, a link to the fpm registry and a mention of fpm-search would be nice. Note there is a getline function in M\_io. The examples could be added to the fpm example repostory, or a new repository could be started with the examples. ---
**Author:** ![awvwgk](https://yyz2.discourse-cdn.com/free1/user_avatar/fortran-lang.discourse.group/awvwgk/32/154_2.png) [@awvwgk](https://fortran-lang.discourse.group/u/awvwgk)\ **Post date:** [December 12, 2021, 3:54pm UTC](https://fortran-lang.discourse.group/t/starting-the-fpm-user-documentation/2338/10 "2021-12-12T15:54:30Z")
> [@urbanjost](#): > > a link to the fpm registry and a mention of fpm-search would be nice Good idea, I will look into writing a tutorial for using fpm plugins using fpm-search and interacting with the registry as example. Added it to the list in [[pull] main from fortran-lang:main by pull[bot] · Pull Request #6 · awvwgk/fpm-docs · GitHub](https://github.com/awvwgk/fpm-docs/issues/6). > [@urbanjost](#): > > Note there is a getline function in M\_io I was hoping we can add one to stdlib: [Procedure to read whole line to deferred length character · Issue #595 · fortran-lang/stdlib · GitHub](https://github.com/fortran-lang/stdlib/issues/595). Do you want to propose the implementation from M\_io for inclusion in stdlib? > [@urbanjost](#): > > The examples could be added to the > fpm example repostory, or a new repository could be started with the examples. The source code for the tutorial is available [here](https://github.com/awvwgk/fpm-docs/tree/main/src/tutorial/dependencies) as fpm project. I’m using a _literalinclude_ in the tutorial source to include parts of the source code as needed, with the right structuring I can incrementally build up files like the package manifest while walking the reader through the steps. The first manifest for example is created with ````nohighlight ```{literalinclude} ../../src/tutorial/dependencies/fpm.toml :language: toml :caption: fpm.toml :lines: 1-6 :emphasize-lines: 4-6 ``` ```` Next step is set up a separate workflow to test all example Fortran source to verify it keeps working. ---
**Author:** ![urbanjost](https://avatars.discourse-cdn.com/v4/letter/u/0ea827/32.png) [@urbanjost](https://fortran-lang.discourse.group/u/urbanjost)\ **Post date:** [December 12, 2021, 4:39pm UTC](https://fortran-lang.discourse.group/t/starting-the-fpm-user-documentation/2338/11 "2021-12-12T16:39:11Z")
The basic idea of the two getlines is the same except mine is implemented as a function instead of a subroutine, so assuming it will be discussed it does not matter what it starts with much. I actually thought there was one in like that in stdlib already. Mine does a few odd things with using a local string and then copying it to the output at the end because of some old issues with allocatable character variables. A few things to note is that the algorithm does not work robustly if PAD=‘YES’ is not set on the input file, and that if the file is not open as a stream you technically run into problems if the system line length limit is hit; but there is no good way to open stdin as a stream in Fortran. Now-adays those limits are set so large they are very unlikely to cause a problem, and it is somewhat up to the compiler what happens anyway. ---
**Author:** ![awvwgk](https://yyz2.discourse-cdn.com/free1/user_avatar/fortran-lang.discourse.group/awvwgk/32/154_2.png) [@awvwgk](https://fortran-lang.discourse.group/u/awvwgk)\ **Post date:** [December 14, 2021, 8:08pm UTC](https://fortran-lang.discourse.group/t/starting-the-fpm-user-documentation/2338/12 "2021-12-14T20:08:56Z")
I moved the fpm documentation to the Fortran-lang GitHub org, now it is really official: > **[GitHub - fortran-lang/fpm-docs: Documentation repository for the Fortran...](https://github.com/fortran-lang/fpm-docs)** > > Documentation repository for the Fortran package manager (fpm) - GitHub - fortran-lang/fpm-docs: Documentation repository for the Fortran package manager (fpm) Next step is to put it up under [https://fpm.fortran-lang.org](https://fpm.fortran-lang.org) (done 🎉) ---
**Author:** ![Neels](https://avatars.discourse-cdn.com/v4/letter/n/9f8e36/32.png) [@Neels](https://fortran-lang.discourse.group/u/Neels)\ **Post date:** [December 15, 2021, 10:30am UTC](https://fortran-lang.discourse.group/t/starting-the-fpm-user-documentation/2338/13 "2021-12-15T10:30:07Z")
This is a very good idea and makes some things clearer for me. I have a request: As a solely Windows user I have never used a package manager and did not even know about such tools until I started looking at Python. Is it maybe possible to add an introduction that explains what it is, the need for a package manager and why I need it on Windows. A large number of Windows users work only in tools like Visual Studio and never do any compiling or running from a command window. ---
**Author:** ![urbanjost](https://avatars.discourse-cdn.com/v4/letter/u/0ea827/32.png) [@urbanjost](https://fortran-lang.discourse.group/u/urbanjost)\ **Post date:** [December 15, 2021, 10:52am UTC](https://fortran-lang.discourse.group/t/starting-the-fpm-user-documentation/2338/14 "2021-12-15T10:52:08Z")
There have been experiments with an fpm gui > [@Experimenting with a GUI for fpm](https://fortran-lang.discourse.group/t/experimenting-with-a-gui-for-fpm/1186): > > I have been experimenting a bit with a simple GUI for fpm. Before it is actually useful for anyone else, a lot of work still has to be done, but I have been able to retrieve and build (or rather attempt to build ;)) a few packages. Here is a screenshot: It is implemented in Tcl/Tk, which makes it easy to use on Windows, Linux and OSX alike. The things it currently is capable of are: Display a list of packages (by reading the file registry.toml) Clone (retrieve) the reposi… and other discussions about how to integrate fpm into IDE packages. Are you more interested in how to use fpm from IDEs and GUIs or the pros of using a terminal/CLI interface? I think both topics would be good to have materials gathered into tutorials on, but given the choice which are you most interested in? ---
**Author:** ![vmagnin](https://yyz2.discourse-cdn.com/free1/user_avatar/fortran-lang.discourse.group/vmagnin/32/28_2.png) [@vmagnin](https://fortran-lang.discourse.group/u/vmagnin)\ **Post date:** [January 13, 2022, 5:25pm UTC](https://fortran-lang.discourse.group/t/starting-the-fpm-user-documentation/2338/15 "2022-01-13T17:25:43Z")
> [@awvwgk](#): > > Also, we can translate the docs 🎉. If you would like to contribute a translation, just search for the `de` identifiers in the `Makefile` and the `pages/conf.py` to add a new language and run Sebastian @awvwgk , I have now some time to work on a French translation of fpm-docs. I have successfully forked it and configured it for French, except that I don’t see anything related to language identifiers in `pages/conf.py`. And in the left margin of the compiled site, the “fr” identifier does not appear (but I can access file:///home/osboxes/fpm-docs/\_build/html/fr/index.html with my browser). I plan to use [poedit](https://poedit.net/) and [DeepL](https://www.deepl.com/translator) to accelerate the work (I have found 246 text blocks to translate). Any help for the French translation will of course be welcome 🙂 ---
**Author:** ![awvwgk](https://yyz2.discourse-cdn.com/free1/user_avatar/fortran-lang.discourse.group/awvwgk/32/154_2.png) [@awvwgk](https://fortran-lang.discourse.group/u/awvwgk)\ **Post date:** [January 13, 2022, 5:45pm UTC](https://fortran-lang.discourse.group/t/starting-the-fpm-user-documentation/2338/16 "2022-01-13T17:45:00Z")
> [@vmagnin](#): > > I have now some time to work on a French translation of fpm-docs. Thanks a lot, feel free to open a tracking issue. > [@vmagnin](#): > > I have successfully forked it and configured it for French, except that I don’t see anything related to language identifiers in `pages/conf.py` . And in the left margin of the compiled site, the “fr” identifier does not appear (but I can access file:///home/osboxes/fpm-docs/\_build/html/fr/index.html with my browser). I moved the language navigation to a template rather than keeping it the `conf.py` file, which seems more robust: > If you search for one of the existing language identifiers you can find the two relevant places (I still have to document the process in detail): ```nohiglight ❯ rg zh_CN . ./Makefile 4:LANGUAGES ?= en de zh_CN es ./pages/_templates/sbt-sidebar-footer.html 5: {%- for lang in ('zh_CN', 'de', 'en', 'es', ) %} ``` ---
**Author:** ![vmagnin](https://yyz2.discourse-cdn.com/free1/user_avatar/fortran-lang.discourse.group/vmagnin/32/28_2.png) [@vmagnin](https://fortran-lang.discourse.group/u/vmagnin)\ **Post date:** [January 13, 2022, 5:54pm UTC](https://fortran-lang.discourse.group/t/starting-the-fpm-user-documentation/2338/17 "2022-01-13T17:54:52Z")
> [@awvwgk](#): > > feel free to open a tracking issue. Done! > > > This thread tracks the translation of the documentation to French. Feel free to …post either in French or English in this threads, whatever seems most appropriate. And I have successfully edited `pages/_templates/sbt-sidebar-footer.html` ---
**Author:** ![vmagnin](https://yyz2.discourse-cdn.com/free1/user_avatar/fortran-lang.discourse.group/vmagnin/32/28_2.png) [@vmagnin](https://fortran-lang.discourse.group/u/vmagnin)\ **Post date:** [January 14, 2022, 9:41am UTC](https://fortran-lang.discourse.group/t/starting-the-fpm-user-documentation/2338/18 "2022-01-14T09:41:57Z")
@awvwgk I have just forked the latest fpm-docs. If I just put `fr` in the `Makefile` and in `pages/_templates/sbt-sidebar-footer.html`, then type the `$ make gettext` command, I can see that some files of the other languages are also modified: ```bash $ git status On branch main Your branch is up to date with 'origin/main'. Changes not staged for commit: (use "git add ..." to update what will be committed) (use "git restore ..." to discard changes in working directory) modified: Makefile modified: locale/de/LC_MESSAGES/index.po modified: locale/es/LC_MESSAGES/index.po modified: locale/zh_CN/LC_MESSAGES/index.po modified: locale/zh_CN/LC_MESSAGES/tutorial.po modified: pages/_templates/sbt-sidebar-footer.html ``` I am confused and I don’t know if this is OK. For example, the `git diff` command shows in the `locale/de/LC_MESSAGES/index.po` file changes like: ```diff -#: ../../pages/index.md:122 +#: ../../pages/index.md:123 +msgid "{fa}`cubes` Registry" +msgstr "" + +#: ../../pages/index.md:125 +msgid "" +"There are already many packages available for use with fpm, providing an " +"easily accessible and rich ecosystem of general purpose and high-" +"performance code. For a full list of packages checkout the [fpm " +"registry](https://fortran-lang.org/packages/fpm). New packages can be " +"submitted to the registry [here](https://github.com/fortran-lang/fpm-" +"registry)." +msgstr "" + +#: ../../pages/index.md:130 msgid "{fa}`newspaper` News" msgstr "{fa}`newspaper` Aktuelles" -#: ../../pages/index.md:124 +#: ../../pages/index.md:132 ``` Should I commit only the changes in the fr files? Or commit all? ---
**Author:** ![awvwgk](https://yyz2.discourse-cdn.com/free1/user_avatar/fortran-lang.discourse.group/awvwgk/32/154_2.png) [@awvwgk](https://fortran-lang.discourse.group/u/awvwgk)\ **Post date:** [January 14, 2022, 9:55am UTC](https://fortran-lang.discourse.group/t/starting-the-fpm-user-documentation/2338/19 "2022-01-14T09:55:55Z")
The `gettext` target will always update all po files, in case they don’t match the latest page source anymore. Which is okay, just ignore the language files you are not interested in. ---
**Author:** ![awvwgk](https://yyz2.discourse-cdn.com/free1/user_avatar/fortran-lang.discourse.group/awvwgk/32/154_2.png) [@awvwgk](https://fortran-lang.discourse.group/u/awvwgk)\ **Post date:** [January 18, 2022, 9:41pm UTC](https://fortran-lang.discourse.group/t/starting-the-fpm-user-documentation/2338/20 "2022-01-18T21:41:57Z")
@Arjen I opened an issue for a Dutch translation of the fpm docs: > > > This thread tracks the translation of the documentation to Dutch. Feel free to p…ost either in Dutch or English in this threads, whatever seems most appropriate. > > cc @arjenmarkus Let me know if you have any questions regarding the workflow to add a new language. It is not properly documented yet ;), but you can find some hints in this thread already. This is something I really have to fix ([Document localisation and internationalisation workflow · Issue #5 · fortran-lang/fpm-docs · GitHub](https://github.com/fortran-lang/fpm-docs/issues/5)). [Next page](https://fortran-lang.discourse.group/t/starting-the-fpm-user-documentation/2338.md?page=2)