The patches in the attachment show the effect of using colored boxes instead of destination marks.

Take latest cwebmac.tex (ver. 3.69) and test.w from the attachment.

First apply patch cwebmac-dvi.patch:

<get clean cwebmac.tex>
patch -p0 < cwebmac-dvi.patch
cweave test.w
tex '\let\pdf+ \input test.tex'
dvipdfm test.dvi
mv test.pdf test1.pdf

Then apply patch cwebmac-pdf.patch:

<get clean cwebmac.tex>
patch -p0 < cwebmac-pdf.patch
cweave test.w
pdftex test.tex
mv test.pdf test2.pdf

Now compare test1.pdf and test2.pdf

I see two problems:

1. for pdf mode there are only two occurrences of \pdfdest (red and green), while for dvi mode there are three occurrences of setting destination marks (red, green and blue). I would like to point out
   that in pdf mode there is \makebookmarks macros, which does the same job more clearly, than it is done in dvi mode.
2. in dvi mode link to first section points before date, not before the section itself, as in pdf mode

In a section of the file ctangle.w, when the TeX part is empty and the C part is an unnamed section starting with @c or @p, how about start with

@
@c

rather than @ @c at the beginning of the section? When you start the section with @ @c, the first line of the C part comes out in the same line as the section number, which is a bit strange to see. This applies to common.w and cweave.w files as well.
Thank you.

• u8"..." ✅
• u"..." ✅
• U"..." ✅

Work has started in cwebbin.

In the attached tarball line.tar.gz CWEB source file line.w gets converted by CTANGLE into line.c. This includes two #line directives inside the #ifdef STAT block.

Running the GCC preprocessor without STAT

gcc -E line.c -o line-noSTAT.i

and with STAT

gcc -E -DSTAT line.c -o line-STAT.i

shows different line numbers after the #endif directive, refering to the return statement in # 20 "line.w" (incorrect when STAT is not defined) and # 13 "line.w" (correct when STAT is defined).

This seems to be a bug in the preprocessor, although it is reported that “Microsoft Visual Studio” has similar problems.

A common “solution” would be if CTANGLE wrote #line 13 "line.w" right after the #endif statement, fixing any ambiguity for the preprocessor.

gb_words.w gets clobbered after section 23, because hash_prime gets treated as a type instead of as a value; see attached gb_words.pdf.

A temporary solution is

typedef Vertex @[*hash_table[hash_prime]@];

but, of course, we can't impose that on The Stanford GraphBase et al.

• cwebman.tex, page 26, should display updated information from common.toc.
• pdfctwimac.tex and pdfproofmac.tex use \Blue instead of \PDFlinkcolor in the \pdfURL macro; in future, this will be straightened out by cwebacromac.tex.
• the singular @*1 in cweave.w should be demoted to @* as in ctangle.w.

As is decently well known, plain TeX's “underscore” character is actually

{\leavevmode \kern.06em \vbox{\hrule width.3em}}

It looks nice enough, but when copying and pasting text that has an underscore, it turns into a space. The usual way to fix this is to mess with text encoding, and I figured dealing with that would not be worth the trouble. However, I recently found out about a PDF feature called ActualText that allows specifying alternative text for an element of the page. See for example this question on TeX.SE.

Not only could this be used for making underscores copy as underscores, but it could also be used for identifiers formatted as Tex, since they could render completely differently from how they appear in the C source code. Whether it would be worth doing for characters like ∧ and ¬ (to make them copy as && and !) is up for debate.

Is this capability something that belongs in CWEB, perhaps as an option (so that extra TeX would not be output if PDF is not the target)? Would it be desirable? If so, then I will implement it.

Although CWEB 3.0 learned to put while directly after the statement after do, Don Knuth continues to add @+ in almost all such situations. This results in

...\5
\2\5
\&{while}

which is not reduced to a single space.

Production rules 33 and 118 and 153 should replace the single blank space with app(opt); app('9'); similar to rules 4, 14, 42, 88.

It might be interesting to replace the type definitions of eight_bits and sixteen_bits in common.h with the modern C99 definitions from <stdint.h>, i.e., uint8_t and uint16_t resp. See C data types for details.

The same holds for C99 bool: boolean type from <stdbool.h>.

If either web file or change file is not found, or both, then .tex file is created, containing just "\input cwebma".
Afterwards it is necessary to remove this file manually.
The warning would be enough.

Section §1 of queen.w gets clobbered.

Temporary fix:

diff --git a/queen.w b/queen.w
index 6d9d09b..f22164b 100644
--- a/queen.w
+++ b/queen.w
@@ -18,12 +18,12 @@ You might find it interesting to compare the output of {\sc QUEEN} with
 the contents of \.{queen.gb}; the former is intended to be readable
 by human beings, the latter by computers.
 
-@p
+@p@t$\!\!\!$@>@+
 #include "gb_graph.h" /* we use the {\sc GB\_\,GRAPH} data structures */
 #include "gb_basic.h" /* we test the basic graph operations */
 #include "gb_save.h" /* and we save our results in ASCII format */
 @#
-main()
+@;main()
 {@+Graph *g,*gg,*ggg;
   g=board(3L,4L,0L,0L,-1L,0L,0L); /* a graph with rook moves */
   gg=board(3L,4L,0L,0L,-2L,0L,0L); /* a graph with bishop moves */

queen_bad.pdf

pdftex and dvipdfm produce different results.

Please help me to understand why bookmarks (aka outlines) in cwebmac.tex produce the following errors:

# dvipdfmx
dvipdfmx:warning: PDF destination "xvii" not defined.

# pdftex
pdfTeX warning (dest): num19 has been referenced but does
not exist, replaced by a fixed one

Steps to reproduce:

wget http://www-cs-faculty.stanford.edu/~uno/programs/reflect.w.gz
gunzip reflect.w.gz
wget http://www-cs-faculty.stanford.edu/~uno/programs/reflect.ch.gz
gunzip reflect.ch.gz

First check that bookmarks in reflect1.pdf and reflect2.pdf are OK without using change file:

# dvipdfmx
            cweave reflect.w
            tex '\let\pdf+ \input reflect.tex'
            dvipdfmx reflect.dvi
            mv reflect.pdf reflect1.pdf

# pdftex
            cweave reflect.w
            pdftex reflect.tex
            mv reflect.pdf reflect2.pdf

Then use change file, which outputs only changed sections with "\let\maybe=\iffalse"

# dvipdfm
            cweave reflect.w reflect.ch
            tex '\let\pdf+ \input reflect.tex'
            dvipdfm reflect.dvi
            mv reflect.pdf reflect3.pdf

# pdftex
            cweave reflect.w reflect.ch
            pdftex reflect.tex
            mv reflect.pdf reflect4.pdf

As we see, in reflect3.pdf and reflect4.pdf bookmarks are present, even for sections which are not changed, and they do not have destination marks.

I tried to figure out how bookmarks in cwebmac.tex are implemented, but I could not understand this in full details. I also asked a question here:

http://tex.stackexchange.com/questions/301174/question-about-maketoks-macros-from-cwebmac-tex

Some technical documentation about how bookmarks are implemented in cwebmac.tex is very necessary. Could you give some technical details please?

👋 just curious, what is the license for this project. I was kind of assuming it would be Latex2e, but I saw there is one clause difference between the two.

Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions.

Can you clarify it or maybe include LICENSE or COPYING as part of the source tarball distribution? Thanks a lot!

Even older versions (CWEB 3.64c) weave

do {
   ...
} while (...);

into TeX code with two \5 between the closing curly brace and while. Confirmed in the printed Stanford GraphBase.

examples/wmerge.w

line 88
@:caddr_t}{\bf caddr_t@>
==>
@:caddr_t}{\bf caddr\_t@>

========

in examples directory

% cweave wmerge
This is CWEAVE (Version 3.64)
*1*23*30*40*43
Writing the output file...*1*23*30*40*43
Writing the index...
Done.
(No errors were found.)
% tex wmerge
This is TeX, Version 3.14159265 (TeX Live 2018) (preloaded format=tex)
(./wmerge.tex
(/usr/local/texlive/2018/texmf-dist/tex/plain/knuth-lib/cwebmac.tex) *1
[1] [2] [3] [4] [5] [6] [7] [8] [9] [10] [11] *23 [12] [13] [14] *30 [15]
[16] [17] *40 [18] *43 Index: (./wmerge.idx
! Missing $ inserted.
<inserted text> 
                $
<to be read again> 
                   _
<argument> \9{caddr_t}{\bf caddr_
                                 t}
\I #1, #2.->\par \hangindent 2em\noindent #1
                                            :\kern 1em \ifacro \pdfnote #2.\...
l.12 \I\9{caddr_t}{\bf caddr_t}, 6.
                                   
? 

Section 240 of CWEAVE defines the module named

@<Check that '=' or '==' follows this section name, and
      emit the scraps to start the section definition@>

This should probably have `\.=' or something similar.

C99/C++11 introduced "variadic macros", but CWEAVE objects to

@d wterm(FMT,...) fprintf(out,FMT,##__VA_ARGS__)

CTANGLE has no problem with this line.

Replacing this with

@d wterm@t\4\,@>@[FMT,...]@>@t\quad@>fprintf(out,FMT,##__VAR_ARGS__)

makes CWEAVE happy, but the C compiler bails on wterm ( output by CTANGLE.

Note that the explicit

#define wterm(FMT,...)@t\quad@>fprintf(out,FMT,##__VA_ARGS__)

works with both CWEAVE and CTANGLE and their output, apart from the necessary @t\quad@> helper.

👋 while I was trying to update the livecheck for the formula in homebrew side, I found that is no license for the repo? I wonder if we can add a SPDX license for the project. Thanks!

DEK uses the curious construct

function declaration with ARGS macro;@+@t}\6{@>
function definition without ARGS macro but K&R parameters

in MMIX modules mmixal.w, mmix-arith.w, mmix-config.w, mmix-io.w, mmix-mem.w, mmix-sim.w, and mmmix.w.

The new CWEB grammar for support of both K&R and ANSI functions indents the

function declaration with ARGS macro
    function definition together with the
    arguments;

Leaving out the @t}\6{@> as in mmotype.w is the natural solution.

Overall, the MMIX code is quite messy in this respect, intermingling function declarations and definitions and global (non-static!) variables.

A significantly better approach is used in mmix-pipe.w, separating @<Prototypes@> and @<Subroutines@> (internal and external).

• Use splint to detect possible problems
• Use size_t for ”all things length”
• Use eight_bits where really necessary; use char/int elsewhere

Both ctangle and cweave complain that a “String didn’t end” for the C++11 construct

const char* s1 = R"foo(
Hello
World
)foo";

Although the tangled C++ code is correct, the resulting TeX output looks just weird.

See https://tug.org/pipermail/tex-live/2023-July/049306.html for details. This affects CWEB and WEB alike.

make doc fails on my system with:

This is TeX, Version 3.141592653 (TeX Live 2022/dev/Debian) (preloaded format=tex)
(./cweave.tex (./cwebmac.tex
(/usr/share/texlive/texmf-dist/tex/generic/iftex/iftex.sty)
! Undefined control sequence.
l.133 ...facrohint \ifacro\acrohinttrue\fi \ifhint
                                                  \acrohinttrue\fi

I'm not the only one having this trouble: https://www.reddit.com/r/tex/comments/18caoq8/cweb_undefined_control_sequence/

Am I maybe missing a package??
dpkg -l | grep texlive lists:

ii  texlive                                       2021.20220204-1                         all          TeX Live: A decent selection of the TeX Live packages
ii  texlive-base                                  2021.20220204-1                         all          TeX Live: Essential programs and files
ii  texlive-binaries                              2021.20210626.59705-1ubuntu0.1          amd64        Binaries for TeX Live
ii  texlive-extra-utils                           2021.20220204-1                         all          TeX Live: TeX auxiliary programs
rc  texlive-font-utils                            2021.20220204-1                         all          TeX Live: Graphics and font utilities
ii  texlive-fonts-recommended                     2021.20220204-1                         all          TeX Live: Recommended fonts
ii  texlive-lang-english                          2021.20220204-1                         all          TeX Live: US and UK English
ii  texlive-latex-base                            2021.20220204-1                         all          TeX Live: LaTeX fundamental packages
ii  texlive-latex-extra                           2021.20220204-1                         all          TeX Live: LaTeX additional packages
ii  texlive-latex-recommended                     2021.20220204-1                         all          TeX Live: LaTeX recommended packages
ii  texlive-luatex                                2021.20220204-1                         all          TeX Live: LuaTeX packages
rc  texlive-metapost                              2021.20220204-1                         all          TeX Live: MetaPost and Metafont packages
ii  texlive-pictures                              2021.20220204-1                         all          TeX Live: Graphics, pictures, diagrams
ii  texlive-plain-generic                         2021.20220204-1                         all          TeX Live: Plain (La)TeX packages
ii  texlive-xetex                                 2021.20220204-1                         all          TeX Live: XeTeX and packages

• Return to the set of values of CWEB 3.64c;
• Introduce modified/enlarged values in CWEBbin;
• There /are/ significant differences between CTANGLE and CWEAVE.

Some people like to start code blocks (compound statements) right after the opening curly brace, i.e.

{ int var;
...
}

or

{ statement;
...
}

This requires a change in Rule 55.

Macro construct

#define exit_test(m) /* we invoke this macro if something goes wrong */\
 {@+fprintf(stderr,"%s!\n(Error code = %ld)\n",m,io_errors);@+return -1;@+}

from gb_io.w gets separated by a full extra line.

See gb_io.pdf.

c++lib.w may deserve extensions for new features of the C++ Standard Library introduced in C++98, C++11, C++14, C++17, …

Also, the extended type systems of C and C++ should better be expressed in such type definition files, instead of cluttering the id_lookup table ever further.

I have noticed on macOS with Adobe Acrobat Reader that output from CWEB 5.0 with make all PDF=pdf fullmanual fails to display any “starred sections”. Now I try to find the cause of the error with CWEB 4.8 (current) and CWEB 3.64c (reference).

Use 3-Heights PDF Validator Online Tool on the CWEB sources (plus user manual).

CWEB 3.64c

CWEB 4.8

CWEB 5.0

The major changes by @texdraft in CWEB 4.3 (and up) bring cweave out of sync with certain constructs like @=...@>. See file var.tar.gz for a small input file and two different output files.

CWEB 4 creates significantly different output thatn CWEB 3.64c

• in case of file misspelling
• -bhp
• +s

See wrap_up, err_print, etc.

Replace raw_ubin * with \MULT and $\times$.

@d def 42 (note the bold #), #define def2 43 (note the non-bold # and the reduced whitespace), and |#define def3 44| are typeset completely differently by CWEAVE.

Any |#...| preprocessor construct will look quite bad. I replace them with \#\&{...}, but that's clumsy.

Reported by @andrewrunxiyu

@* A demonstration of a bug in {\tt CWEAVE}. During my work writing a server
for my new chat protocol in {\tt CWEB}, I think that I've stumped
on a bug. Weaving is done through {\tt cweave bug.w} and then
{\tt pdftex bug.w}. In all code examples below, much code is redacted
to save space. Please look at both examples and anticipate what {\tt CWEAVE}
with {pdf\TeX}'s output will look like before actually weaving it and looking
at the PDF.

@ The following code produces results typeset erroneously.

@d SA struct sockaddr
@c
int main(int argc, chat **argv)
{
auto int server_socket;
/* random stuff */
auto int len = sideof(addr);
int connfd = accept(server_socket, (SA *) &addr, &len);
user_session(connfd);
return 0;
}

@ The following code produces results typeset correctly. It only
differs from the previous example in that {\tt struct sockaddr} is used
directly in the conversion specifier, rather than the {\tt SA} macro. In C,
these two approaches are identical. However, {\tt CWEAVE} fails to recognize
that {\tt SA} is a conversion specifier, and thus produces weird results.

@c
int main(int argc, chat **argv)
{
auto int server_socket;
/* random stuff */
auto int len = sideof(addr);
int connfd = accept(server_socket, (struct sockaddr *) &addr, &len);
user_session(connfd);
return 0;
}

@ I haven't read {\tt CWEAVE}'s internal workings yet because of all the
schoolwork that I have to do at the moment. However, I believe that the
behavior documented above is truely unexpected behavior. From the behavior
above, I assume that the {\tt @@d} macro definitions are not actually replaced
throughout the processing routine of CWEAVE, and is only written into the {\tt
CTANGLE}ed output file and inserted into the {\tt CWEAVE} output. As macro
definitions do not only work for named constants and what I like to call ``mini
functions'', and may be some sort of type alias shortcut, I think {\tt CWEAVE}
should handle macros before checking whether each token is a statement (to typeset
in {\bf boldface} for example, and to adjust indentation and other various aspects).

@ I am Andrew~Yu, a Grade~8 student from YK~Pao School, Shanghai, China
({\tt www.andrewyu.org/}). I've recently got into literate programming
and found a lot of productivity. As international mailing is exceptionally
expensive, I've decided to write this electronic mail first. Thanks!

@* Index.

Commit 4c6cdff breaks reflect.w.

See bug report at https://tug.org/pipermail/tex-k/2021-August/003682.html for details.

Sections 94, 201, and 203 of cweave.w are not formatted correctly when run through

cweave cweave.w
tex cweave.tex
dvips cweave.dvi

or simply

make
make doc

Sorry if this is not the right place to ask this question. I have been trying to automate the creation of a cweb document with github actions:
https://github.com/tvercaut/iad

This currently works but takes about an hour to run due to teh installation of texlive-full. I tried installing only texlive as I thought this would be sufficient to get cweb:
https://manpages.ubuntu.com/manpages/jammy/man1/cweb.1.html

However, it then stumbles by not finding cmacweb despite having found cweave:

cweave -bph ad || (echo "cweave exited with code $? - continue anyway"; exit 0)

! Never used: <Definition for |swrarray|>
! Never used: <debug print angles>
! Never used: <unused fragment one>
! Never used: <unused fragment two>(Did you see the warning message above?)
cweave exited with code 5 - continue anyway
pdftex ad
This is pdfTeX, Version 3.141592653-2.6-1.40.22 (TeX Live 2022/dev/Debian) (preloaded format=pdftex)
 restricted \write18 enabled.
entering extended mode
(./ad.tex
! I can't find file `cwebmac'.
l.1 \input cwebmac
make[1]: *** [Makefile:71: ad_doc] Error 1

Is there a package that can be installed on ubuntu or a step that I would be missing with texlive only to get a fully working cweb setup?

MWE

For whatever reason, tostring_func is recognized as a type (bold), while print_func is not (italic).

@* Pointer-to-function types.

@s MP int
@s mp_number int

@c @2
typedef void (*print_func) (MP mp, mp_number A);

@ @c
typedef char * (*tostring_func) (MP mp, mp_number A);

@* Index.

Debug output

Tracing after l. 9:
@ 
109:*typedef exp ( +ubinop?+ exp...
104: typedef*exp ( +ubinop+ exp ) (...
18: typedef*exp ( +exp+ ) (...
11:*typedef exp +exp+ (...
10:*typedef +exp+ ( raw...
110:*typedef +exp+ ( int exp +,+ raw...
27: typedef +exp+*( -decl_head- exp +,+ raw...
35: typedef +exp+*( -decl_head- +,+ raw...
14: typedef*+exp+ -(+ raw...
110:*typedef +exp+ -(+ int exp ) ;...
27: typedef +exp+*-(+ -decl_head- exp ) ;...
35: typedef +exp+*-(+ -decl_head- ) ;...
13:*typedef +exp+ -cast- ;...
0: typedef*+exp+ -cast- -;-
10:*typedef +exp- -;-
117:*-typedef- -;-
119:*-decl-
Tracing after l. 12:
@*
110:*typedef int +ubinop?+ ( +ubinop?+...
116:*-typedef- +ubinop?+ ( +ubinop?+...
104:*-typedef- +ubinop+ ( +ubinop?+ exp...
104: -typedef-*+ubinop+ ( +ubinop+ exp ) (...
18: -typedef-*+ubinop+ ( +exp+ ) (...
11:*-typedef- +ubinop+ +exp+ (...
18:*-typedef- +exp+ ( raw...
110:*-typedef- +exp+ ( int exp +,+ raw...
27: -typedef- +exp+*( -decl_head- exp +,+ raw...
35: -typedef- +exp+*( -decl_head- +,+ raw...
14: -typedef-*+exp+ -(+ raw...
110:*-typedef- +exp+ -(+ int exp ) ;...
27: -typedef- +exp+*-(+ -decl_head- exp ) ;...
35: -typedef- +exp+*-(+ -decl_head- ) ;...
13:*-typedef- +exp+ -cast- ;...
0: -typedef-*+exp+ -cast- -;-
10:*-typedef- +exp- -;-
117:*-typedef- -;-
119:*-decl-

(Did you see the warning message above?)

Woven output

func_typedef.pdf

C code like

if (...) whatever;
else if (...) whatever;
else break;

shows that break is a tad further apart from else than the if right above.

ctangle should preserve (or automatically add) whitespace in multi-part string initializers like

const char Version[] = "Programme 3.14 (" __DATE__ ")";

If you put __DATE__ directly after the string literal, a C++11 compiler will issue a warning like "invalid suffix on literal" (see C++ reference).

In its current incarnation, ctangle (and cweave) removes any intermediate whitespace in such multi-part initializers.

Sidecase: ctangle produces flawed code for return L'\0'; (which can be remedied with extra parentheses) and case L'\0': (which would be very inconvenient to fix).

RTFM: Private communication pointed to the @= directive, which puts extra material in the tangled C output. Instead of line breaks, one can write

const char Version[] = "Programme 3.14 ("@= @>__DATE__@= @>")";

to add whitespace at the critical spots. Also the TeX output is clearly marked for this.

@i tags in the @y...@z part of a change file result in #line directives for the name of the change file, not of the included file(s).

Prominent example is the extended comm-22p.h file of CWEBBIN, which never gets referenced in ctangle.c (nor cweave.c). Instead, ctang-22p.ch is referenced in #line directives.

The obviously old and probably outdated change files for obscure systems do not match the tuned-up source files:

• comm-bs.ch, ctang-bs.ch, cweav-bs.ch
• comm-ql.ch, ctang-ql.ch, cweav-ql.ch
• comm-vms.ch
• comm-w32.ch

• set all Example codes in |...|
• process cweave prod.w
• replace the Example codes with the TeX equivalents from prod.tex

The new \mark{\topmark} added in line 473 of cwebmac.tex prohibits prod.w to be formatted standalone. After cweave [-e] prod, both tex prod and pdftex prod fail with Missing control sequence \inaccessible inserted.

Is there a cweave option ( or workaround) to process comments as regular comments (not as TEX)?

cweb 3.64e (the win32 version) includes some options that I find really useful that do not seem to be present in cweb 4.3.

• ‘t’ respects both regular and trailing comments.
• ‘g’ respects blank lines.
• ‘z’ indicates plain text comments.

The source for the win32 version does not seem to be available in literateprogramming.com so I was wondering - is there is a way to achieve something similar in cweb 4.3?

I've been using original CWEB to try literate programming for the first time.
Everything was fine, until I noticed a strange formatting when using C99 compound literal syntax.
Then I tried CWEB 4.2, and the problem was not resolved.

Here is a MWE that demonstrates the problem:

@* Hello CWEB.
@c
#include <stdio.h>

struct T {
	int a;
};

struct T tok(void) {
	return (struct T){.a = 1}; // C99 compound literal
}

int main(void)
{
	struct T = tok();
	return 0;
}

This is the output PDF build with cweave and pdftex.

In the meantime, I can try manually breaking the lines with @;, but I can't see how to manually indent/unindent wrongly formatted code.