refactor documentation regarding consistency

[JHenneberg]

Could someone link the file to where the documentation standard is desribed?

I was reading through some documents in doc/specs and realised differenced between those documents.
Mostly the layout looks like following:

---
title: <MODULE_NAME>
---

# The `<MODULE_NAME>` module

[TOC]

## Introduction

## <OPTIONAL_SECTIONS>

## Procedures and methods provided

### `<PROCEDURE_NAME>` - <SHORT_DESCRIPTION>

#### Status

#### Description

#### Syntax

#### Class

#### Argument

#### Result Value

#### Example

stdlib_ascii.md and a lot of other modules are following this convention, but some do not. Sometimes the order of the subsections describing the procedures are different or some subsections are missing. In other documents the hierarchy level is changed. Do you feel there is a need to address this issues? Should this be continued to be discussed in #181 ?

[milancurcic]

Thanks, @JHenneberg and good question. I don't think we have a template for this, and I think we should. @jvdp1 @ivan-pi what did you use as reference when creating the first spec docs in stdlib?

[jvdp1]

Hi. I used the Fortran standard doc Le mar. 31 août 2021 à 18:40, Milan Curcic ***@***.***> a écrit :

…

Thanks, @JHenneberg <https://github.com/JHenneberg> and good question. I don't think we have a template for this, and I think we should. @jvdp1 <https://github.com/jvdp1> @ivan-pi <https://github.com/ivan-pi> what did you use as reference when creating the first spec docs in stdlib? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#503 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AD5RO7HD4Q5OEIFDICCVSETT7UAYBANCNFSM5DEJOQYQ> . Triage notifications on the go with GitHub Mobile for iOS <https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675> or Android <https://play.google.com/store/apps/details?id=com.github.android&referrer=utm_campaign%3Dnotification-email%26utm_medium%3Demail%26utm_source%3Dgithub>.

[milancurcic]

The changes look good to me, thanks @JHenneberg.

[awvwgk]

Thanks for sharing, looks good to me.

[milancurcic]

@JHenneberg I see WIP in the title--would you like to work more on this PR or should we merge it?

[JHenneberg]

I wanted to work more on it, but now that there is a discussion going on about the spec_template.md it can be merged, because depending what changes might come it could be double the work.

[aman-godara]

How about we add 2 small sections in documentation with the name troubleshooting and caution?
We know not everyone has the patience to go through the whole documentation only to look for a particular function they are looking for. If we add a small troubleshooting section and caution section (they are not needed for all functions though but for some) as per the use case it will make documentation way easier to reference to.

For example, if a person is using find function of stdlib_strings and got stuck, well then probably it is because the output of the function is 0 (suggesting that the input substring was NOT FOUND) which can be added in caution section.

or if a person is using slice function and got weird outputs then probably because of the person hasn't specified stride argument which then automatically got deduced by the function leading to smart behaviour (which the user doesn't want and wasn't aware of) so this can be added in troubleshooting section for slice function.

Also, sometimes Fortan throws bad errors, so the documentation can provided some possible ways in which a user might have added errors when using a function.
For example, if you give integer indexes to a stringlist, it gives 'binding not found error' which doesn't say that use fidx and bidx instead of integer index.

[aman-godara]

Also, removing those trailing double spaces which looked useless make .md file (markdown) look different:

taken from https://stdlib.fortran-lang.org/page/specs/stdlib_string_type.html#to_title-function.

in .md files (markdown):
Double spaces + Enter means new line. Double Enter also means new line.
space + Enter DOESN'T mean new line and means a single space only.
Enter means a single space
more than one space means a single space only

Previously with double spaces this used to look like this:

taken from GitHub and NOT from https://stdlib.fortran-lang.org

To try out one can use https://www.markdowntutorial.com or some other website but the point is that markdown files look different when viewed on GitHub from what they do when we are editing them on some editor like VS Code.

Those single spaces before Enter, I never knew, turned out to be redundant.

[aman-godara]

These double spaces are redundant because the two Enters did the job here of creating a new line

[JHenneberg]

Also, removing those trailing double spaces which looked useless make .md file (markdown) look different:

taken from https://stdlib.fortran-lang.org/page/specs/stdlib_string_type.html#to_title-function.

in .md files (markdown):
Double spaces + Enter means new line. Double Enter also means new line.
space + Enter DOESN'T mean new line and means a single space only.
Enter means a single space
more than one space means a single space only

Previously with double spaces this used to look like this:

taken from GitHub and NOT from https://stdlib.fortran-lang.org

To try out one can use https://www.markdowntutorial.com or some other website but the point is that markdown files look different when viewed on GitHub from what they do when we are editing them on some editor like VS Code.

Those single spaces before Enter, I never knew, turned out to be redundant.

Ok Interesting. Did not know about this double space feature, but I guess its better because more intuitive to do this similar to LaTeX using double Enter for new line.

Can you add this information to #504 ?

And this too:

How about we add 2 small sections in documentation with the name troubleshooting and caution?
We know not everyone has the patience to go through the whole documentation only to look for a particular function they are looking for. If we add a small troubleshooting section and caution section (they are not needed for all functions though but for some) as per the use case it will make documentation way easier to reference to.

For example, if a person is using find function of stdlib_strings and got stuck, well then probably it is because the output of the function is 0 (suggesting that the input substring was NOT FOUND) which can be added in caution section.

or if a person is using slice function and got weird outputs then probably because of the person hasn't specified stride argument which then automatically got deduced by the function leading to smart behaviour (which the user doesn't want and wasn't aware of) so this can be added in troubleshooting section for slice function.

Also, sometimes Fortan throws bad errors, so the documentation can provided some possible ways in which a user might have added errors when using a function.
For example, if you give integer indexes to a stringlist, it gives 'binding not found error' which doesn't say that use fidx and bidx instead of integer index.