tinycc manpage

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
8 messages Options
Reply | Threaded
Open this post in threaded view
|

tinycc manpage

Sudipto Mallick
When I compiled a recent version of tinycc from mob, I looked at the
source of the manpage. I don't like it. I learnt about the mdoc(7)
format for writing man pages and thought to use that format for the
tcc man page. The rewrite is attached.

What do you think about this mdoc formatted manual page?

This is not yet complete (see TODOs). Please give suggestion to complete it.

_______________________________________________
Tinycc-devel mailing list
[hidden email]
https://lists.nongnu.org/mailman/listinfo/tinycc-devel

tcc.1 (12K) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: tinycc manpage

Ant_222
Sudipto Mallick:

> When I compiled a recent version of tinycc from mob, I
> looked at the source of the manpage. I don't like it.

What did not you like?

> I learnt about the mdoc(7) format for writing man pages
> and thought to use that format for the tcc man page. The
> rewrite is attached.

The processed result is attached. While processing, GNU
Troff reported the following warnings:

   mdoc warning: A .Bl directive has no matching .El (#287)
   mdoc warning: Empty input line #376
   mdoc warning: Empty input line #387
   mdoc warning: Empty input line #392
   mdoc warning: Empty input line #394
   mdoc warning: Empty input line #409

> What do you think about this mdoc formatted manual page?

I disike lines longer than 78 characters and lack of
vertical spacing between logical sections. You can do them
like this:

   end of previous secgtion
   .
   .Sh SYNOPSIS
   .
   text text text.

> Please give suggestion to complete it.

I personally prefer the original -man package to -mdoc...

_______________________________________________
Tinycc-devel mailing list
[hidden email]
https://lists.nongnu.org/mailman/listinfo/tinycc-devel

tcc.1.txt (9K) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: tinycc manpage

Michael Matz-4
In reply to this post by Sudipto Mallick
Hello,

On Fri, 25 Dec 2020, Sudipto Mallick wrote:

> When I compiled a recent version of tinycc from mob, I looked at the
> source of the manpage. I don't like it.

In which sense?  tcc.1 is a generated file, it's not supposed to be
edited.  The source is tcc-doc.texi, i.e. texinfo, via texi2pod and
pod2man.  So, are you sure you're barking at the right tree?

> I learnt about the mdoc(7) format for writing man pages and thought to
> use that format for the tcc man page. The rewrite is attached.

While -mdoc certainly is nicer than -man it's both trumped (IMHO) by
perlpod and texinfo, in writability.

> What do you think about this mdoc formatted manual page?

I think it's nicer than the current generated tcc.1 file, and I think it's
somewhat more purist to directly write mdoc files for a project like TCC,
instead of generating them.  But I also think that something like this
needs to be easy to write/edit, and in this case I'd argue that texinfo is
just fine.

> This is not yet complete (see TODOs). Please give suggestion to complete
> it.


Ciao,
Michael.

_______________________________________________
Tinycc-devel mailing list
[hidden email]
https://lists.nongnu.org/mailman/listinfo/tinycc-devel
Reply | Threaded
Open this post in threaded view
|

Re: tinycc manpage

Sudipto Mallick
In reply to this post by Ant_222
On 12/26/20, Anton Shepelev <[hidden email]> wrote:
> What did not you like?
Uglyness and unnecessary bloat.

> While processing, GNU
> Troff reported the following warnings:
>
>    mdoc warning: A .Bl directive has no matching .El (#287)
>    mdoc warning: Empty input line #376
>    mdoc warning: Empty input line #387
>    mdoc warning: Empty input line #392
>    mdoc warning: Empty input line #394
>    mdoc warning: Empty input line #409
>
Fixed! I am still learning to use mdoc(7) :-)

>> What do you think about this mdoc formatted manual page?
> I disike lines longer than 78 characters and lack of
> vertical spacing between logical sections. You can do them
> like this:
>
>    end of previous secgtion
>    .
>    .Sh SYNOPSIS
>    .
>    text text text.
>
Okay.
I am attaching the improved version of the man page.
Thanks for your suggestions.
--Sudipto

_______________________________________________
Tinycc-devel mailing list
[hidden email]
https://lists.nongnu.org/mailman/listinfo/tinycc-devel

tcc.1 (12K) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: tinycc manpage

Sudipto Mallick
In reply to this post by Michael Matz-4
On 12/26/20, Michael Matz <[hidden email]> wrote:
> In which sense?  tcc.1 is a generated file, it's not supposed to be
> edited.  The source is tcc-doc.texi, i.e. texinfo, via texi2pod and
> pod2man.  So, are you sure you're barking at the right tree?
> While -mdoc certainly is nicer than -man it's both trumped (IMHO) by
> perlpod and texinfo, in writability.

As I am reformatting it, I do not find it hard to write. It must have
been writable enough to be used in writing almost all manual pages in
OpenBSD etc.
Also current setup depends on perl to be installed, which is not a
hard requirement, but still ...
mdoc(7) was specifically designed to write high quality manual pages
and it is available on most platforms.
You may like to look at the HTML generated by mandoc(1) for the
reformatted manpage: https://smlckz.tilde.institute/tcc.html

>> What do you think about this mdoc formatted manual page?
> I think it's nicer than the current generated tcc.1 file, and I think it's
> somewhat more purist to directly write mdoc files for a project like TCC,
> instead of generating them.  But I also think that something like this
> needs to be easy to write/edit, and in this case I'd argue that texinfo is
> just fine.
There's also texi2mdoc which is written in C, but I haven't tried that.
Also, I think we need man pages for libtcc, what do you think?
--Sudipto

_______________________________________________
Tinycc-devel mailing list
[hidden email]
https://lists.nongnu.org/mailman/listinfo/tinycc-devel
Reply | Threaded
Open this post in threaded view
|

Re: tinycc manpage

Ant_222
Sudipto Mallick to Michael Matz:

> As  I am reformatting it, I do not find it hard to
> write. It must have been  writable  enough  to  be
> used in writing almost all manual pages in OpenBSD
> etc.  Also current setup depends on perl to be in-
> stalled,  which  is  not  a  hard requirement, but
> still ...

I agree that *roff syntax is simultaneosly  concise,
writable,  and  readable,  whereas texinfo is a huge
package with a verbose syntax  and  dependencies  on
LaTeX  and  other third-party formatters. That said,
*roff would be the natural choice for TCC because of
its similar minimalist ideology, but since the offi-
cial documentaion tool for TCC is  Texinfo,  I  fear
your good effort will not appreciated...

> There's  also texi2mdoc which is written in C, but
> I haven't tried that.

That means using the makrup language  from  a  large
system,  but  converting into the language of a sim-
pler system by means of a C program. Everybody  will
not  like it...  I think that using Texinfo directly
is better.


_______________________________________________
Tinycc-devel mailing list
[hidden email]
https://lists.nongnu.org/mailman/listinfo/tinycc-devel
Reply | Threaded
Open this post in threaded view
|

Re: tinycc manpage

Sudipto Mallick
On 12/26/20, Anton Shepelev <[hidden email]> wrote:
> I agree that *roff syntax is simultaneosly  concise,
> writable,  and  readable,  whereas texinfo is a huge
> package with a verbose syntax  and  dependencies  on
> LaTeX  and  other third-party formatters. That said,
> *roff would be the natural choice for TCC because of
> its similar minimalist ideology, but since the offi-
> cial documentaion tool for TCC is  Texinfo,  I  fear
> your good effort will not appreciated...

Hmm. I am just asking for the change only of the manpage, not the
whole documentation. The documentation and manpage can be kept in sync
without much problem, I think.

I am new here, I do not know whose approval I need to push the
changes. Whom to ask for approval?

>> There's  also texi2mdoc which is written in C, but
>> I haven't tried that.
> That means using the makrup language  from  a  large
> system,  but  converting into the language of a sim-
> pler system by means of a C program. Everybody  will
> not  like it...  I think that using Texinfo directly
> is better.
Well... Same with the current texi2pod.pl.
except for being written in C means texi2mdoc do not need an external
dependency :-)
--Sudipto

_______________________________________________
Tinycc-devel mailing list
[hidden email]
https://lists.nongnu.org/mailman/listinfo/tinycc-devel
Reply | Threaded
Open this post in threaded view
|

Re: tinycc manpage

Ant_222
Sudipto Mallick:

> I am new here, I do not know whose approval I need
> to push the changes. Whom to ask for approval?

Not being a contributor to TCC, I  can't  tell  you.
Since  nobody has answered, chances are no one among
the readers of this mailing list  is  interested  in
tranditional  hand-crafted  man-pages  for  TCC  and
libtcc, but I think many users ourside may like  the
idea... Good luck.


_______________________________________________
Tinycc-devel mailing list
[hidden email]
https://lists.nongnu.org/mailman/listinfo/tinycc-devel