[PATCH 0/4] Documentation improvements and fixes

[PATCH 0/4] Documentation improvements and fixes

[Glenn Washburn]

These patches are pretty self explanatory. The first patch was requested by
Daniel and Daniel suggested the link to the INSTALL file from the git web
repo.

Glenn

Glenn Washburn (4):
  docs: Add sentence on where Debian packages can be searched for online
  docs: Update development docs to include information on running test
    suite
  docs: Fix broken links in development docs
  docs: Add documentation on packages for building documentation

 INSTALL            | 12 ++++++++++--
 docs/grub-dev.texi | 22 +++++++++++++++++-----
 2 files changed, 27 insertions(+), 7 deletions(-)

-- 
2.27.0

[PATCH 1/4] docs: Add sentence on where Debian packages can be searched for online

[Glenn Washburn]

Signed-off-by: Glenn Washburn <development@efficientek.com>
---
 INSTALL | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/INSTALL b/INSTALL
index 38d8d5a4d..8a2b617f3 100644
--- a/INSTALL
+++ b/INSTALL
@@ -5,7 +5,8 @@ This is the GRUB.  Welcome.
 This file contains instructions for compiling and installing the GRUB.
 
 Where this document refers to packages names, they are named according to the
-Debian 11 package repositories.
+Debian 11 package repositories. These packages can be found by searching
+https://packages.debian.org/.
 
 The Requirements
 ================
-- 
2.27.0

[PATCH 2/4] docs: Update development docs to include information on running test suite

[Glenn Washburn]

Add a section with minimal description on setting up and running the test
suite with a link to the INSTALL documentation which is a little more
detailed in terms of package requirements.

Signed-off-by: Glenn Washburn <development@efficientek.com>
---
 docs/grub-dev.texi | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/docs/grub-dev.texi b/docs/grub-dev.texi
index fb2cc965e..1beff25a7 100644
--- a/docs/grub-dev.texi
+++ b/docs/grub-dev.texi
@@ -77,6 +77,7 @@ This edition documents version @value{VERSION}.
 * Coding style::
 * Finding your way around::
 * Contributing Changes::
+* Setting up and running test suite::
 * Updating External Code::
 * Porting::
 * Error Handling::
@@ -483,6 +484,17 @@ If your intention is to just get started, please do not submit a inclusion
 request. Instead, please subscribe to the mailing list, and communicate first
 (e.g. sending a patch, asking a question, commenting on another message...).
 
+@node Setting up and running test suite
+@chapter Setting up and running test suite
+
+GRUB is basically a tiny operating system with read support for many file
+systems and which has been ported to a variety of architectures. As such, its
+test suite has quite a few dependencies required to fully run the suite.
+These dependencies are currently documented in the
+@uref{http://git.savannah.gnu.org/cgit/grub.git/tree/INSTALL, INSTALL}
+file in the source repository. Once installed, the test suite can be started
+by running the @command{make check} command from the GRUB build directory.
+
 @node Updating External Code
 @chapter Updating external code
 
-- 
2.27.0

[PATCH 3/4] docs: Fix broken links in development docs

[Glenn Washburn]

Use the Git Book as a reference for documentation on Git as no other link
was provided. Other links were broken because they used @url instead of
@uref and needed a comma separator between link and link text.

Signed-off-by: Glenn Washburn <development@efficientek.com>
---
 docs/grub-dev.texi | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/docs/grub-dev.texi b/docs/grub-dev.texi
index 1beff25a7..3e05def1f 100644
--- a/docs/grub-dev.texi
+++ b/docs/grub-dev.texi
@@ -96,8 +96,8 @@ This edition documents version @value{VERSION}.
 @node Getting the source code
 @chapter Getting the source code
 
-GRUB is maintained using the @uref{GIT revision
-control system}.  To fetch:
+GRUB is maintained using the @uref{https://git-scm.com/book/en/v2,
+GIT revision control system}.  To fetch:
 
 @example
 git clone git://git.sv.gnu.org/grub.git
@@ -346,8 +346,8 @@ manual and try GRUB 2 out to see what you think is missing from there.
 
 Here are additional pointers:
 @itemize
-@item @url{https://savannah.gnu.org/task/?group=grub GRUB's Task Tracker}
-@item @url{https://savannah.gnu.org/bugs/?group=grub GRUB's Bug Tracker}
+@item @uref{https://savannah.gnu.org/task/?group=grub, GRUB's Task Tracker}
+@item @uref{https://savannah.gnu.org/bugs/?group=grub, GRUB's Bug Tracker}
 @end itemize
 
 If you intended to make changes to GRUB Legacy (<=0.97) those are not accepted
@@ -461,7 +461,7 @@ and the FSF clerks have dealt with your copyright assignment.
 @section When you are approved for write access to project's files
 
 As you might know, GRUB is hosted on
-@url{https://savannah.gnu.org/projects/grub Savannah}, thus the membership
+@uref{https://savannah.gnu.org/projects/grub, Savannah}, thus the membership
 is managed by Savannah. This means that, if you want to be a member of this
 project:
 
-- 
2.27.0

[PATCH 4/4] docs: Add documentation on packages for building documentation

[Glenn Washburn]

Signed-off-by: Glenn Washburn <development@efficientek.com>
---
 INSTALL | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

diff --git a/INSTALL b/INSTALL
index 8a2b617f3..a64f63723 100644
--- a/INSTALL
+++ b/INSTALL
@@ -90,6 +90,10 @@ Note that `make check' will run and many tests may complete successfully
 with only a subset of these prerequisites. However, some tests may be
 skipped or fail due to missing prerequisites.
 
+To build the documentation you'll need:
+* texinfo, for the info and html documentation
+* texlive, for building the dvi and pdf documentation (optional)
+
 Configuring the GRUB
 ====================
 
@@ -146,7 +150,10 @@ The simplest way to compile this package is:
   8. Type `make install' to install the programs and any data files and
      documentation.
 
-  9. You can remove the program binaries and object files from the
+  9. Type `make html' or `make pdf' to generate the html or pdf
+     documentation.  Note, these are not built by default.
+
+ 10. You can remove the program binaries and object files from the
      source code directory by typing `make clean'.  To also remove the
      files that `configure' created (so you can compile the package for
      a different kind of computer), type `make distclean'.  There is
-- 
2.27.0

Re: [PATCH 0/4] Documentation improvements and fixes

[Daniel Kiper]

On Fri, Nov 05, 2021 at 02:12:54PM -0500, Glenn Washburn wrote:
> These patches are pretty self explanatory. The first patch was requested by
> Daniel and Daniel suggested the link to the INSTALL file from the git web
> repo.
>
> Glenn
>
> Glenn Washburn (4):
>   docs: Add sentence on where Debian packages can be searched for online
>   docs: Update development docs to include information on running test
>     suite
>   docs: Fix broken links in development docs
>   docs: Add documentation on packages for building documentation

One nit, we should use "https://" instead of "http://" today.
I will fix it before push. Otherwise for all patches
Reviewed-by: Daniel Kiper <daniel.kiper@oracle.com>

Daniel