taskGNU Astronomy Utilities - Tasks: task #16297, Add "How to read this...

 
 

You are not allowed to post comments on this tracker with your current authentication level.

task #16297: Add "How to read this manual" section in the book

Submitter:  Mohammad Akhlaghi <makhlaghi>
Submitted:  Tue 20 Dec 2022 02:40:48 PM UTC
   
 
Should Start On:  Tue 20 Dec 2022 12:00:00 AM UTC Should be Finished on:  Tue 20 Dec 2022 12:00:00 AM UTC
Category:  Book Priority:  5 - Normal
Item Group:  Enhancement Status:  Postponed
Privacy:  Public Assigned to:  makhlaghi
Percent Complete:  0% Open/Closed:  Open
Effort:  0.00

Fri 23 Dec 2022 08:37:28 AM UTC, comment #4: 

Oh we can actually use the UTF-8 characters in texinfo with the @U{HEX-NUMBER-HERE} instruction. We can also define MACROs for things we need that aren't there by default. For example, the \leftarrow in my previous screenshots can be produced by @U{2190}. The output looks the same in the pdf, but it actually prints a '←' in the 'info' and 'html' versions instead of a lame '\leftarrow'.

For example:


@c 'leftarrow' is reserved, so a 'u' prefix
@c better indicates that this is a 'unicode'
@macro uleftarrow
@U{2190}
@end macro


and then simply:


Then use @command{make} with number of processors for faster execution:
@example
$ make -j8 # @uleftarrow{} put number of processors here
@print{} EXAMPLE TEXT
@result{} EXAMPLE RESULT
@end example
@noindent
Or in short, just use:
@example
$ make -j$(nproc)
@end example


Which will produce a beautiful left arrow in pdf, html, and the info.


Pedram Ashofteh-Ardakani <pedram>
Group Member
Fri 23 Dec 2022 08:19:28 AM UTC, comment #3: 

Oops, don't mind the previous info.jpg, here is the new one (file new-info.jpg)


Pedram Ashofteh-Ardakani <pedram>
Group Member
Fri 23 Dec 2022 08:14:44 AM UTC, comment #2: 

Another note: most likely, we do not need to add unicode characters in the 'texi' file. They are not readable in the source code. But using the programming glyphs will be readable.

As a last resort, we can use the @math operator to create shapes we need (which are also readable). For example, in the following screenshots, you can see the pdf, info, and html output of the sample code below:


[...] TeXinfo initialization
Then use @command{make} with number of processors for faster execution:
@example
$ make -j8 # @math{\leftarrow} put number of processors here
@print{} EXAMPLE TEXT
@result{} EXAMPLE RESULT
@end example
@noindent
Or in short, just use:
@example
$ make -j$(nproc)
@end example
[...] The rest of the document


(file html.jpg)
(file info.jpg)
(file pdf.jpg)


Pedram Ashofteh-Ardakani <pedram>
Group Member
Thu 22 Dec 2022 05:42:01 PM UTC, comment #1: 

Indeed this would be a more friendly introduction for newcomers.

Maybe we can also use the 'programming glyphs' in 'texinfo' for better visual guidance. Then we can simply introduce them in the 'Convensions' section and hopefully it will be a better distinction.

For instance, to show a printed text while program is still running you might use @print{} which produces the BOX DRAWINGS LIGHT VERTICAL AND LEFT character '┤' or u2524. Or another one, would be the result of a program, in other words, the output with @result{} which produces the '⇒' or RIGHTWARDS DOUBLE ARROW character or 'u21d2'.

  • note: to type unicode characters, you can simply hold down Ctrl+shift and press 'u' and then type '2524' for example.
Pedram Ashofteh-Ardakani <pedram>
Group Member
Tue 20 Dec 2022 02:40:48 PM UTC, original submission:  

The Gnuastro book has become very extensive (843 pages in version 0.19). This can make it hard for someone new to Gnuastro to get a generic and high-level idea of how to read it.

We should add this meta-manual (manual about the manual!) in a section called "How to read this manual" early in the introduction section, maybe after the "Quick start" and "List of Gnuastro programs" (that was brought to the "Introduction" chapter in commit 431660bdc; after version 0.19).

Mohammad Akhlaghi <makhlaghi>
Group administrator

 

(Note: upload size limit is set to 16384 kB, after insertion of the required escape characters.)

Attached Files
file #54159:  utf8-info.jpg added by pedram (16KiB - image/jpeg)
file #54160:  utf8-pdf.jpg added by pedram (17KiB - image/jpeg)
file #54161:  utf8-html.jpg added by pedram (17KiB - image/jpeg)
file #54158:  new-info.jpg added by pedram (17KiB - image/jpeg)
file #54155:  html.jpg added by pedram (9KiB - image/jpeg)
file #54156:  info.jpg added by pedram (21KiB - image/jpeg)
file #54157:  pdf.jpg added by pedram (16KiB - image/jpeg)

 

Depends on the following items: None found

Items that depend on this one: None found

 

Carbon-Copy List
  • -email is unavailable- added by pedram (Posted a comment)
  • -email is unavailable- added by makhlaghi (Submitted the item)
  • -email is unavailable- added by makhlaghi
  •  

    There are 0 votes so far. Votes easily highlight which items people would like to see resolved in priority, independently of the priority of the item set by tracker managers.

     

    Follow 10 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2022-12-23 pedram Attached File- Added utf8-info.jpg, #54159
        Attached File- Added utf8-pdf.jpg, #54160
        Attached File- Added utf8-html.jpg, #54161
    2022-12-23 pedram Attached File- Added new-info.jpg, #54158
    2022-12-23 pedram Attached File- Added html.jpg, #54155
        Attached File- Added info.jpg, #54156
        Attached File- Added pdf.jpg, #54157
    2022-12-23 pedram Carbon-CopyRemoved -email is unavailable- -
    2022-12-20 makhlaghi Carbon-Copy- Added -email is unavailable-
        Carbon-Copy- Added -email is unavailable-

    Back to the top

    Powered by Savane 3.13-461b.
    Corresponding source code