Extend documentation - Githubissues

ottok commented 4 years ago

This seems like a nifty tool but it is a bit difficult to get started.

Please add a section that documents how to install it.

If it is included in some Linux distro, please link to it. I did not find any hl package at https://packages.ubuntu.com/search?suite=groovy&searchon=names&keywords=hl as an example.

Also, please tell visitors in the intro how this tool differs from other similar tools, such as https://github.com/cornet/ccze.

mbornet-hl commented 4 years ago

Hi, thank you for your comment. Have you had a look at the wiki (https://github.com/mbornet-hl/hl/wiki) ? There are some installation instructions : do you think something is missing ? Maybe I could add an INSTALL file with installation instructions, but you could anyway find interesting information in the wiki. At the present time, to my knowledge, hl is only included in ArchLinux. I don't have time to create RPM or .deb packages. Maybe one day, who knows ... If you want to create packages for hl, feel free to do it. I didn't know the ccze command you're talking about. Apparently, it's only dedicated to the colorization of log files, while hl also can transparently colorize the output of commands. hl also can detect changes from one line to the following one, and is able to start colorizing on a line when it detects a start marker, and stop when it detects a stop marker potentially many lines below, as <begin> and <end>, or <mark> and </mark>, or { and }, and so on. Please have a look at the articles published in a french Linux magazine :

Even if you don't read french, you'll be able to read shell commands and have a look at the screenshots that show some of the possibilities of hl.

Another difference with ccze (I think) is that you don't need to write new code when you want to create a new configuration, you just need to add the new configuration to an existing configuration file, or to create it in a new configuration file, or to just specify the options list as command line arguments. hl is also able to deal with regex priority in case they partially or totally overlap. Options are one letter options, and options preceeded by two dashes are configuration names. So as you can see, there are several differences between ccze and hl. Also hl is NOT able to convert timestamps, nor to generate HTML files : it just colorizes text according to specified regular expressions.

I'll appreciate your comments about hl.

Thanks. Regards.

Martial

mbornet-hl commented 4 years ago

Hi, do you need more information, or may I close this issue ? Regards,

Martial

ottok commented 4 years ago

I checked the commits for https://github.com/mbornet-hl/hl/commits/master/README.md and looks much better now!

I would also like to see sections INSTALL and CONTRIBUTE in the README, so that people know how to install it and how to contribute. If you don't want to make the deb and rpm yourself, maybe somebody can contribute (hint: I am a Debian Developer :))..

mbornet-hl commented 4 years ago

Hi, I added a small paragraph name Contribute in the README, so if you still want to create Debian packages, you're welcome !

Regards,

Martial

ottok commented 3 years ago

Can you share a link to the hl page in Arch Linux? I could check out how the packaging is done in Arch. Even better, add that link to your README.

I am currently struggling with how to correctly build hl. WIP: https://github.com/ottok/hl/tree/master/debian

I also have some difficulties navigating the repository, there are so many files for which I don't understand the purpose. As a packager I should be able to understand what all the packages are and where they go. There is currently no "make install" in the project to look at. I also noticed the repository has a lot of excess stuff that don't belong to version control, for example binary files.

ottok commented 3 years ago

And what exactly are the build dependencies?

# dpkg -l | grep lex
ii  flex                      2.6.4-8          amd64        fast lexical analyzer generator
ii  libfl-dev:amd64           2.6.4-8          amd64        static library for flex (a fast lexical analyzer generator)
ii  libfl2:amd64              2.6.4-8          amd64        SHARED library for flex (a fast lexical analyzer generator)
ii  libmpc3:amd64             1.2.0-1          amd64        multiple precision complex floating-point library

# make
cd src; make
make[1]: Entering directory '/build/hl/src'
/usr/bin/ld: cr_main.o: warning: relocation against `yyin' in read-only section `.text'
/usr/bin/ld: cr_main.o: in function `cr_read_config_file':
cr_main.c:(.text+0x185): undefined reference to `yyin'
/usr/bin/ld: cr_main.c:(.text+0x18c): undefined reference to `yyin'
/usr/bin/ld: cr_main.c:(.text+0x1e5): undefined reference to `yylex'
/usr/bin/ld: warning: creating DT_TEXTREL in a PIE
collect2: error: ld returned 1 exit status
make[1]: *** [Makefile:17: hl] Error 1
make[1]: Leaving directory '/build/hl/src'
make: *** [Makefile:6: hl] Error 2

mbornet-hl commented 3 years ago

Can you share a link to the hl page in Arch Linux? I could check out how the packaging is done in Arch. Even better, add that link to your README.

I added a link to an ArchLinux web page in the README : https://aur.archlinux.org/packages/hl-git/ .

ottok commented 3 years ago

So indeed the best only build dependency is flex. But as you can see in the copy-paste output, it didn't build with the gcc and flex version is n Debian unstable.

mbornet-hl commented 3 years ago

My system is a Devuan ascii :

$ cat /etc/os-release     
PRETTY_NAME="Devuan GNU/Linux ascii"
NAME="Devuan GNU/Linux"
ID=devuan
ID_LIKE=debian
HOME_URL="https://www.devuan.org/"
SUPPORT_URL="https://devuan.org/os/community"
BUG_REPORT_URL="https://bugs.devuan.org/"

Here is how I install hl on a Devuan system :

~/tmp $ git clone https://github.com/mbornet-hl/hl
Cloning into 'hl'...
remote: Enumerating objects: 242, done.
remote: Counting objects: 100% (242/242), done.
remote: Compressing objects: 100% (179/179), done.
remote: Total 1051 (delta 127), reused 155 (delta 53), pack-reused 809
Receiving objects: 100% (1051/1051), 2.31 MiB | 26.00 KiB/s, done.
Resolving deltas: 100% (560/560), done.

~/tmp $ cd hl
/home/machine/mb/tmp/hl

~/tmp/hl $ l
total 192
-rw-r--r--  1 mb mb 35201 Nov 20 23:33 LICENSE
-rw-r--r--  1 mb mb    94 Nov 20 23:33 Makefile
-rw-r--r--  1 mb mb 33805 Nov 20 23:33 README.md
-rw-r--r--  1 mb mb  2669 Nov 20 23:33 README.txt
-rw-r--r--  1 mb mb   167 Nov 20 23:33 TODO.txt
drwxr-xr-x 12 mb mb  4096 Nov 20 23:33 bin
drwxr-xr-x  2 mb mb  4096 Nov 20 23:33 completion
drwxr-xr-x  2 mb mb  4096 Nov 20 23:33 config_files
drwxr-xr-x  2 mb mb  4096 Nov 20 23:33 doc
drwxr-xr-x  3 mb mb  4096 Nov 20 23:33 examples
-rwxr-xr-x  1 mb mb 48440 Nov 20 23:33 hl
-rw-r--r--  1 mb mb  5242 Nov 20 23:33 hl.wiki.git
drwxr-xr-x  2 mb mb  4096 Nov 20 23:33 hl_alternate
drwxr-xr-x  2 mb mb  4096 Nov 20 23:33 hl_bin
drwxr-xr-x  2 mb mb  4096 Nov 20 23:33 images
drwxr-xr-x  2 mb mb  4096 Nov 20 23:33 man1
drwxr-xr-x  2 mb mb  4096 Nov 20 23:33 man5
drwxr-xr-x  2 mb mb  4096 Nov 20 23:33 quality
drwxr-xr-x  2 mb mb  4096 Nov 20 23:33 scripts
drwxr-xr-x  2 mb mb  4096 Nov 20 23:33 src

~/tmp/hl $ cd src
/home/machine/mb/tmp/hl/src

~/tmp/hl/src $ make
cc    -c -o cr_main.o cr_main.c
cc    -c -o cr_gpri.o cr_gpri.c
lex  -t cr_lex.l > cr_lex.c
cc    -c -o cr_lex.o cr_lex.c
./hl: version 1.93

Nothing more.

Here are the versions of cc /lex / yacc :

~/tmp/hl/src $ dpkg -l | egrep 'gcc|flex|bison'
ii  bison                        2:3.0.4.dfsg-1+b1   amd64               YACC-compatible parser generator
ii  flex                         2.6.1-1.3           amd64               fast lexical analyzer generator
ii  gcc                          4:6.3.0-4           amd64               GNU C compiler
ii  gcc-6                        6.3.0-18+deb9u1     amd64               GNU C compiler
ii  gcc-6-base:amd64             6.3.0-18+deb9u1     amd64               GCC, the GNU Compiler Collection (base package)
ii  libbison-dev:amd64           2:3.0.4.dfsg-1+b1   amd64               YACC-compatible parser generator - development library
ii  libdom4j-java                1.6.1+dfsg.3-2+deb9 all                 flexible XML framework for Java
ii  libfl-dev:amd64              2.6.1-1.3           amd64               static library for flex (a fast lexical analyzer generator)
ii  libgcc-6-dev:amd64           6.3.0-18+deb9u1     amd64               GCC support library (development files)
ii  libgcc1:amd64                1:6.3.0-18+deb9u1   amd64               GCC support library
ii  linux-compiler-gcc-6-x86     4.9.228-1           amd64               Compiler for Linux on x86 (meta-package)

ottok commented 3 years ago

Ok, I got it building in Debian Buster. Seems the code is incompatible with the Flex version in Debian Sid (latest flex). You should look into it.

The quality assurance tool in Lintian also complained about quite a few things:

N: Using profile debian/main. N: Starting on group hl/1.93 N: Unpacking packages in group hl/1.93 N: ---- N: Processing changes file hl (version 1.93, arch source amd64) ... N: ---- N: Processing source package hl (version 1.93, arch source) ... P: hl source: package-does-not-install-examples examples/ P: hl source: source-contains-prebuilt-binary hl_alternate/hl E: hl source: source-is-missing hl_alternate/hl P: hl source: source-contains-prebuilt-binary bin/1.91/hl E: hl source: source-is-missing bin/1.91/hl P: hl source: source-contains-prebuilt-binary bin/1.92/hl E: hl source: source-is-missing bin/1.92/hl P: hl source: source-contains-prebuilt-binary bin/1.93/hl E: hl source: source-is-missing bin/1.93/hl P: hl source: source-contains-prebuilt-binary bin/1.87/i686/debian/hl E: hl source: source-is-missing bin/1.87/i686/debian/hl P: hl source: source-contains-prebuilt-binary bin/1.90/i686/debian/hl E: hl source: source-is-missing bin/1.90/i686/debian/hl P: hl source: source-contains-prebuilt-binary bin/1.46/amd64/debian/7.8/hl E: hl source: source-is-missing bin/1.46/amd64/debian/7.8/hl P: hl source: source-contains-prebuilt-binary bin/1.46/i386/debian/5.0.6/hl E: hl source: source-is-missing bin/1.46/i386/debian/5.0.6/hl P: hl source: source-contains-prebuilt-binary bin/1.51/amd64/debian/7.8/hl E: hl source: source-is-missing bin/1.51/amd64/debian/7.8/hl P: hl source: source-contains-prebuilt-binary bin/1.51/i386/debian/5.0.6/hl E: hl source: source-is-missing bin/1.51/i386/debian/5.0.6/hl P: hl source: source-contains-prebuilt-binary bin/1.59/amd64/debian/7.8/hl E: hl source: source-is-missing bin/1.59/amd64/debian/7.8/hl P: hl source: source-contains-prebuilt-binary bin/1.59/i386/debian/5.0.6/hl E: hl source: source-is-missing bin/1.59/i386/debian/5.0.6/hl P: hl source: source-contains-prebuilt-binary bin/1.61/amd/debian/7.8/hl E: hl source: source-is-missing bin/1.61/amd/debian/7.8/hl P: hl source: source-contains-prebuilt-binary bin/1.61/i386/debian/5.0.6/hl E: hl source: source-is-missing bin/1.61/i386/debian/5.0.6/hl P: hl source: source-contains-prebuilt-binary bin/1.62/amd/debian/7.8/hl E: hl source: source-is-missing bin/1.62/amd/debian/7.8/hl P: hl source: source-contains-prebuilt-binary bin/1.62/i386/debian/5.0.6/hl E: hl source: source-is-missing bin/1.62/i386/debian/5.0.6/hl P: hl source: source-contains-prebuilt-binary bin/1.62/i686/centos/5.5/hl E: hl source: source-is-missing bin/1.62/i686/centos/5.5/hl P: hl source: package-uses-old-debhelper-compat-version 10 W: hl source: newer-standards-version 4.5.0 (current is 4.3.0) I: hl source: testsuite-autopkgtest-missing N: ---- N: Processing buildinfo package hl (version 1.93, arch amd64 source) ... N: ---- N: Processing binary package hl (version 1.93, arch amd64) ... I: hl: hardening-no-bindnow usr/bin/hl E: hl: copyright-should-refer-to-common-license-file-for-gpl W: hl: binary-without-manpage usr/bin/hl N: Finished processing group hl/1.93

I also myself noticed quite a few quality issues:

You have the binary 'hl' in version control, and in fact many versions of it. In git you should have only source files.
You have (two) man pages, but the "make" does not install them anywhere.
You have a bash completition file, but "make" does not install it anywhere.
There are many cfg config files. Should "make" install these somewhere? Maybe /usr/share/hl/*?
There is a quality assurance script hl_QA but the documentation is in French. Do you have some kind of test suite etc that a CI system could run?

sergeevabc commented 1 year ago

Dear @mbornet-hl, could you be so kind to generate .exe for the rest of us who are ordinary Windows users w/o compiler?

mbornet-hl commented 1 year ago

Dear Aleksandr, I'm sorry but I don't use Windows and I 'm not able to generate or test a ".exe" file. I currently have no solution for you. Kind regards.

tkapias commented 1 year ago

Currently it is a bit complicated to install HL entirely without having read all your documentation (readme, wiki, blog page).

It's a pity, the first thing a user, even an expert, is looking for is a section that explains from A to Z how to install or compile the application. Most of the time it is better if this section is right after the introduction and the Features, or at the end of the Readme, even if it means referring to the Wiki.

I suggest the following text for Linux:

Install

Linux

Requirements

gcc
lex
make
git

Debian based distro instalaltion:

sudo apt install gcc flex make git

Build & Install

git clone --depth=1 https://github.com/mbornet-hl/hl

cd hl
make clean
make

# executable
sudo cp hl /usr/local/bin/hl

# documentation
mkdir -p /usr/local/share/man/man1/ /usr/local/share/man/man5/
sudo cp man1/hl.1 /usr/local/share/man/man1/
sudo cp man5/hl.5 /usr/local/share/man/man5/

# if you use bash, the project include a completion script
sudo apt install bash-completion
sudo mkdir -p /usr/local/share/bash-completion/completions/
sudo cp completion/complete_hl /usr/local/share/bash-completion/completions/hl

# install some default configuration files
sudo mkdir -p /etc/hl/config.d/
sudo cp config_files/* /etc/hl/config.d/
mkdir -p $HOME/.config/hl/config.d/
cp config_files/* $HOME/.config/hl/config.d/

# add this variable export to .profile or .bashrc if you use a custom location
export HL_CONF=$HOME/.config/hl/config.d:/etc/hl/config.d

mbornet-hl / hl

Extend documentation #17

Install

Linux

Requirements

Build & Install