further split examples and fix some autodoc links issues due to wrong declarations

Author: jalvesz

doc/specs/stdlib_system.md

@@ -174,7 +174,7 @@ The result is a real value representing the elapsed time in seconds, measured fr
 
 ### Syntax
 
-`delta_t = ` [[stdlib_system(module):elapsed(subroutine)]] `(process)`
+`delta_t = ` [[stdlib_system(module):elapsed(interface)]] `(process)`
 
 ### Arguments
 
@@ -212,7 +212,7 @@ in case of process hang or delay.
 
 ### Syntax
 
-`call ` [[stdlib_system(module):wait(subroutine)]] `(process [, max_wait_time])`
+`call ` [[stdlib_system(module):wait(interface)]] `(process [, max_wait_time])`
 
 ### Arguments
 
@@ -243,7 +243,7 @@ This is especially useful for monitoring asynchronous processes and retrieving t
 
 ### Syntax
 
-`call ` [[stdlib_system(module):update(subroutine)]] `(process)`
+`call ` [[stdlib_system(module):update(interface)]] `(process)`
 
 ### Arguments
 
@@ -269,7 +269,7 @@ This interface is useful when a process needs to be forcefully stopped, for exam
 
 ### Syntax
 
-`call ` [[stdlib_system(module):kill(subroutine)]] `(process, success)`
+`call ` [[stdlib_system(module):kill(interface)]] `(process, success)`
 
 ### Arguments
 
@@ -298,7 +298,7 @@ It ensures that the requested sleep duration is honored on both Windows and Unix
 
 ### Syntax
 
-`call ` [[stdlib_system(module):sleep(subroutine)]] `(millisec)`
+`call ` [[stdlib_system(module):sleep(interface)]] `(millisec)`
 
 ### Arguments
 
@@ -324,7 +324,7 @@ This function is highly efficient and works during the compilation phase, avoidi
 
 ### Syntax
 
-`result = ` [[stdlib_system(module):is_windows(function)]] `()`
+`result = ` [[stdlib_system(module):is_windows(interface)]] `()`
 
 ### Return Value
 
@@ -359,7 +359,7 @@ If the OS cannot be identified, the function returns `OS_UNKNOWN`.
 
 ### Syntax
 
-`os = [[stdlib_system(module):get_runtime_os(function)]]()`
+`os = ` [[stdlib_system(module):get_runtime_os(function)]] `()`
 
 ### Class
 
@@ -396,7 +396,7 @@ This caching mechanism ensures negligible overhead for repeated calls, unlike `g
 
 ### Syntax
 
-`os = [[stdlib_system(module):OS_TYPE(function)]]()`
+`os = ` [[stdlib_system(module):OS_TYPE(function)]]`()`
 
 ### Class
 
@@ -431,7 +431,7 @@ It is designed to work across multiple platforms. On Windows, paths with both fo
 
 ### Syntax
 
-`result = [[stdlib_system(module):is_directory(function)]] (path)`
+`result = ` [[stdlib_system(module):is_directory(function)]]`(path)`
 
 ### Class
 
@@ -471,7 +471,7 @@ It reads as an empty file. The null device's path varies by operating system:
 
 ### Syntax
 
-`path = [[stdlib_system(module):null_device(function)]]()`
+`path = ` [[stdlib_system(module):null_device(function)]]`()`
 
 ### Class
 
@@ -506,7 +506,7 @@ The function provides an optional error-handling mechanism via the `state_type`
 
 ### Syntax
 
-`call [[stdlib_system(module):delete_file(subroutine)]] (path [, err])`
+`call ` [[stdlib_system(module):delete_file(subroutine)]]` (path [, err])`
 
 ### Class
 Subroutine
@@ -546,8 +546,9 @@ i.e `\` for windows and `/` for others
 
 ### Syntax
 
-`res = [[stdlib_system(module):joinpath(interface)]] (p1, p2)`
-`res = [[stdlib_system(module):joinpath(interface)]] (p)`
+`res = ` [[stdlib_system(module):joinpath(interface)]] ` (p1, p2)`
+
+`res = ` [[stdlib_system(module):joinpath(interface)]] ` (p)`
 
 ### Class
 Pure function
@@ -562,24 +563,17 @@ Pure function
 
 The resultant path.
 
-### Example
-
-```fortran
-{!example/system/example_path_1.f90!}
-```
-
 ## `operator(/)`
 
-Join two paths according to the platform specific path-separator,
-Behavior exactly similar to `joinpath`
+Alternative syntax to`joinpath` using an overloaded operator. Join two paths according to the platform specific path-separator.
 
 ### Status
 
 Experimental
 
 ### Syntax
 
-`p = lval + rval`
+`p = lval / rval`
 
 ### Class
 
@@ -588,6 +582,7 @@ Pure function.
 ### Arguments
 
 `lval`: A character string, `intent(in)`.
+
 `rval`: A character string, `intent(in)`.
 
 ### Result value
@@ -597,7 +592,7 @@ The result is an `allocatable` character string
 #### Example
 
 ```fortran
-{!example/system/example_path_1.f90!}
+{!example/system/example_path_join.f90!}
 ```
 
 ## `splitpath` - splits a path immediately following the last separator
@@ -613,7 +608,7 @@ splitting it into most of the times a directory and a file name.
 
 ### Syntax
 
-`call [[stdlib_system(module):splitpath(interface)]] (p, head, tail)`
+`call `[[stdlib_system(module):splitpath(interface)]]`(p, head, tail)`
 
 ### Class
 Subroutine
@@ -637,7 +632,7 @@ The splitted path. `head` and `tail`.
 ### Example
 
 ```fortran
-{!example/system/example_path_1.f90!}
+{!example/system/example_path_splitpath.f90!}
 ```
 
 ## `basename` - The last part of a path
@@ -652,7 +647,7 @@ This function returns the last part of a path after removing trailing path separ
 
 ### Syntax
 
-`res = [[stdlib_system(module):basename(interface)]] (p)`
+`res = ` [[stdlib_system(module):basename(interface)]]`(p)`
 
 ### Class
 Function
@@ -672,7 +667,7 @@ A character string.
 ### Example
 
 ```fortran
-{!example/system/example_path_1.f90!}
+{!example/system/example_path_basename.f90!}
 ```
 
 ## `dirname` - Everything except the last part of the path
@@ -687,7 +682,7 @@ This function returns everything except the last part of a path.
 
 ### Syntax
 
-`res = [[stdlib_system(module):dirname(interface)]] (p)`
+`res = ` [[stdlib_system(module):dirname(interface)]]`(p)`
 
 ### Class
 Function
@@ -707,5 +702,5 @@ A character string.
 ### Example
 
 ```fortran
-{!example/system/example_path_1.f90!}
+{!example/system/example_path_dirname.f90!}
 ```

example/system/CMakeLists.txt

@@ -11,7 +11,7 @@ ADD_EXAMPLE(process_5)
 ADD_EXAMPLE(process_6)
 ADD_EXAMPLE(process_7)
 ADD_EXAMPLE(sleep)
-ADD_EXAMPLE(path_1)
-ADD_EXAMPLE(path_1_windows)
-ADD_EXAMPLE(path_2)
-ADD_EXAMPLE(path_2_windows)
+ADD_EXAMPLE(path_basename)
+ADD_EXAMPLE(path_dirname)
+ADD_EXAMPLE(path_join)
+ADD_EXAMPLE(path_splitpath)

example/system/example_path_1.f90

@@ -0,0 +1,16 @@
+! Usage of splitpath, dirname, basename
+program example_path_splitpath
+    use stdlib_system, only: basename, ISWIN
+    character(len=:), allocatable :: p1
+
+    if( ISWIN ) then
+        p1 = 'C:\Users'
+    else
+        p1 = '/home'
+    endif 
+    
+    print *, 'basename of '// p1 // ' -> ' // basename(p1) 
+    ! basename of C:\Users -> Users
+    ! OR
+    ! basename of /home -> home
+end program example_path_splitpath

example/system/example_path_1_windows.f90

@@ -0,0 +1,16 @@
+! Usage of splitpath, dirname, basename
+program example_path_splitpath
+    use stdlib_system, only: dirname, ISWIN
+    character(len=:), allocatable :: p1, head, tail
+
+    if( ISWIN ) then
+        p1 = 'C:\Users' ! C:\Users
+    else
+        p1 = '/home' ! /home
+    endif 
+
+    print *, 'dirname of '// p1 // ' -> ' // dirname(p1) 
+    ! dirname of C:\Users -> C:\
+    ! OR
+    ! dirname of /home -> /
+end program example_path_splitpath

example/system/example_path_2.f90

@@ -0,0 +1,22 @@
+! Usage of joinpath, operator(/)
+program example_path_join
+    use stdlib_system, only: joinpath, operator(/), ISWIN
+    character(len=:), allocatable :: p1, p2, p3
+    character(len=20) :: parr(4)
+
+    if( ISWIN ) then
+        p1 = 'C:'/'Users'/'User1'/'Desktop'
+        p2 = joinpath('C:\Users\User1', 'Desktop')
+    else
+        p1 = ''/'home'/'User1'/'Desktop'
+        p2 = joinpath('/home/User1', 'Desktop')
+    end if
+
+    parr = [character(len=20) :: '', 'home', 'User1', 'Desktop']
+    p3 = joinpath(parr)
+
+    ! (p1 == p2 == p3) = '/home/User1/Desktop' OR 'C:'/'Users'/'User1'/'Desktop'
+    print *, p1 ! /home/User1/Desktop OR 'C:'/'Users'/'User1'/'Desktop'
+    print *, "p1 == p2: ", p1 == p2 ! T
+    print *, "p2 == p3: ", p2 == p3 ! T
+end program example_path_join

example/system/example_path_2_windows.f90

@@ -0,0 +1,25 @@
+! Usage of splitpath, dirname, basename
+program example_path_splitpath
+    use stdlib_system, only: joinpath, splitpath, ISWIN
+    character(len=:), allocatable :: p1, head, tail
+
+    if( ISWIN ) then
+        p1 = joinpath('C:\Users\User1', 'Desktop') ! C:\Users\User1\Desktop
+    else
+        p1 = joinpath('/home/User1', 'Desktop') ! /home/User1/Desktop
+    endif 
+    
+    call splitpath(p1, head, tail)
+    ! head = /home/User1 OR C:\Users\User1, tail = Desktop
+    print *, p1 // " -> " // head // " + " // tail 
+    ! C:\Users\User1\Desktop -> C:\Users\User1 + Desktop
+    ! OR
+    ! /home/User1/Desktop -> /home/User1 + Desktop
+
+    call splitpath(head, p1, tail)
+    ! p1 = /home OR C:\Users, tail = User1
+    print *, head // " -> " // p1 // " + " // tail 
+    ! C:\Users\User1 -> C:\Users + User1
+    ! OR
+    ! /home/User1 -> /home + User1
+end program example_path_splitpath