peterfeicht / cppreference-doc Goto Github PK

Hi Peter,

could you do a new release?

C++20 is right around the corner and the wiki changed quite substantial since the last release.

Please don't forget to update cppreference-doxygen-web.tag.xml.

The favicon seems to be broken, I think the content type needs to be set explicitly to image/vnd.microsoft.icon in Vivaldi only.

After downloading the prepared archive and unzipping it in the root of cppreference-doc then running make doc_html I get this error

make doc_html
mkdir -p output
./preprocess.py --src reference --dst output/reference
Traceback (most recent call last):
  File "/usr/lib/python3.11/shutil.py", line 825, in move
    os.rename(src, real_dst)
FileNotFoundError: [Errno 2] No such file or directory: 'output/reference/upload.cppreference.com/mwiki' -> 'output/reference/common'

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "/home/eric/src/Manuals/cppreference-doc/./preprocess.py", line 84, in <module>
    main()
  File "/home/eric/src/Manuals/cppreference-doc/./preprocess.py", line 46, in main
    preprocess.rearrange_archive(root)
  File "/home/eric/src/Manuals/cppreference-doc/commands/preprocess.py", line 59, in rearrange_archive
    shutil.move(os.path.join(root, 'upload.cppreference.com/mwiki'), data_path)
  File "/usr/lib/python3.11/shutil.py", line 845, in move
    copy_function(src, real_dst)
  File "/usr/lib/python3.11/shutil.py", line 436, in copy2
    copyfile(src, dst, follow_symlinks=follow_symlinks)
  File "/usr/lib/python3.11/shutil.py", line 256, in copyfile
    with open(src, 'rb') as fsrc:
         ^^^^^^^^^^^^^^^
FileNotFoundError: [Errno 2] No such file or directory: 'output/reference/upload.cppreference.com/mwiki'

and if I run make doc_html again it says nothing to be done for doc_html.

The last release was on 2022.07.30, it has been a year, can we make a new release?

Repos of other languages of this repo releases less frequently than yours (I really appreciate it for the help your up-to-date offline doc gives me), so I wget from the origin to get the Chinese doc every couple of months. Since the access to cppreference.com is very slow in my region, I tried to write a github action script but have not finished the work.

Are you glad to write the script to auto fetch the source from cppreference.com (maybe with some techniques to avoid duplicate request to the website from forks of this repos) and pack it into docs in github actions? If you don't have time, maybe I'll try to write it when I'm not so busy.

Thanks a lot, wishes.

Hello,

In the most recent release the doxygen web tagfile has some weird namespaces that include ( characters. Looks like this might be the result of typo in a config change somewhere causing std::experimental::erase to be treated as a namespace instead of a function, but I don't know enough about how this project works to dive into it myself.

The first example in question appears in cppreference-doxygen-web.tag.xml at line 30706:

  <compound kind="namespace">
    <name>std::experimental::erase(std</name> <!-- this line -->
    <filename></filename>
    <member kind="function">

You'll be able to quickly find others just by skipping through the search results for kind="namespace", since there aren't too many.

Hi PeterFeicht,

could you also provide thehttp://en.cppreference.com/w/File:cppreference-doxygen-web.tag.xml file?
That would be awesome!

Thank you!

There are a bunch of errors when building the Doxygen tag file, caused by duplicate elements when a class overrides base class functions. There are two entries, one for the base class function, one for the override, which conflict (e.g. std::pmr::synchronized_pool_resource::do_allocate).

Preprocessing a single file for the cssless QCH files takes a couple of seconds on my reasonably fast machine, which means a release build will take hours instead of seconds.

One of the hotspots seems to be repeated parsing and dumping of CSS styles from the style DOM element property and back. A possible improvement would be to just use regular expressions for handling most CSS manipulation, if we can make sure that the actual CSS is simple enough for that to work.

What about other than English translation for offline copy? How could I get one for other languages?

I am trying to compile a devhelp book for Mac, found devhelp2qch.py script, but it gives me issues:

./devhelp2qch.py 
Traceback (most recent call last):
  File "./devhelp2qch.py", line 54, in <module>
    main()
  File "./devhelp2qch.py", line 44, in main
    in_tree = etree.parse(src_path, parser)
  File "src/lxml/etree.pyx", line 3424, in lxml.etree.parse
  File "src/lxml/parser.pxi", line 1863, in lxml.etree._parseDocument
TypeError: cannot parse from 'NoneType'

What am I missing?

I am primarily interested in devhelp documentation on Debian/Linux.

Here is what I tried:

wget https://github.com/PeterFeicht/cppreference-doc/releases/download/v20220730/cppreference-doc-20220730.tar.xz
tar xf cppreference-doc-20220730.tar.xz
cd cppreference-doc-20220730/
sudo apt install python3-pip
pip install premailer
sed -i "s/allow_loading_external_files=False/allow_loading_external_files=True/g" ~/.local/lib/python3.10/site-packages/premailer/premailer.py
make -j$(nproc) doc_devhelp

Which quickly gave me the following messages at the end:

...
HTML WARN: output/reference/en/c/language/operator_arithmetic.html:650:6:ERROR:HTML:ERR_TAG_NAME_MISMATCH: Unexpected end tag : li
HTML WARN: output/reference/en/c/language/operator_arithmetic.html:650:11:ERROR:HTML:ERR_TAG_NAME_MISMATCH: Unexpected end tag : ul
HTML WARN: output/reference/en/c/language/operator_arithmetic.html:651:6:ERROR:HTML:ERR_TAG_NAME_MISMATCH: Unexpected end tag : dd
HTML WARN: output/reference/en/c/language/operator_arithmetic.html:651:11:ERROR:HTML:ERR_TAG_NAME_MISMATCH: Unexpected end tag : dl
HTML WARN: output/reference/en/c/language/operator_arithmetic.html:656:6:ERROR:HTML:ERR_TAG_NAME_MISMATCH: Unexpected end tag : li
HTML WARN: output/reference/en/c/language/operator_arithmetic.html:656:11:ERROR:HTML:ERR_TAG_NAME_MISMATCH: Unexpected end tag : ul
HTML WARN: output/reference/en/c/language/operator_arithmetic.html:657:6:ERROR:HTML:ERR_TAG_NAME_MISMATCH: Unexpected end tag : dd
HTML WARN: output/reference/en/c/language/operator_arithmetic.html:657:11:ERROR:HTML:ERR_TAG_NAME_MISMATCH: Unexpected end tag : dl

./build_link_map.py
./index2devhelp.py /usr/share/cppreference/doc/html index-chapters-c.xml  \
    "C Standard Library reference" "cppreference-doc-en-c" "c" \
    index-functions-c.xml "output/devhelp-index-c.xml"
./index2devhelp.py /usr/share/cppreference/doc/html index-chapters-cpp.xml  \
    "C++ Standard Library reference" "cppreference-doc-en-cpp" "cpp" \
    index-functions-cpp.xml "output/devhelp-index-cpp.xml"
./fix_devhelp-links.py "output/devhelp-index-c.xml"  \
    "output/cppreference-doc-en-c.devhelp2"
./fix_devhelp-links.py "output/devhelp-index-cpp.xml" \
    "output/cppreference-doc-en-cpp.devhelp2"
Could not find cpp/header/contract in mapping
Could not find cpp/numeric/special_math in mapping
Could not find cpp/iterator/readable_traits in mapping
Could not find cpp/memory/new/nothrow_t in mapping
Could not find cpp/memory/allocator_arg_t in mapping
Could not find cpp/utility/initializer_list/rbegin2 in mapping
Could not find cpp/utility/initializer_list/rend2 in mapping
Could not find cpp/chrono/operator""h in mapping
Could not find cpp/chrono/operator""min in mapping
Could not find cpp/chrono/operator""s in mapping
Could not find cpp/chrono/operator""ms in mapping
Could not find cpp/chrono/operator""us in mapping
Could not find cpp/chrono/operator""ns in mapping
Could not find cpp/chrono/operator""d in mapping
Could not find cpp/chrono/operator""y in mapping
Could not find cpp/utility/piecewise_construct_t in mapping
Could not find cpp/string/basic_string/operator""s in mapping
Could not find cpp/string/basic_string_view/begin_end_nonmem in mapping
Could not find cpp/string/basic_string_view/begin_end_nonmem in mapping
Could not find cpp/string/basic_string_view/begin_end_nonmem in mapping
Could not find cpp/string/basic_string_view/begin_end_nonmem in mapping
Could not find cpp/string/basic_string_view/begin_end_nonmem in mapping
Could not find cpp/string/basic_string_view/begin_end_nonmem in mapping
Could not find cpp/string/basic_string_view/begin_end_nonmem in mapping
Could not find cpp/string/basic_string_view/begin_end_nonmem in mapping
Could not find cpp/string/basic_string_view/begin_end_nonmem in mapping
Could not find cpp/string/basic_string_view/begin_end_nonmem in mapping
Could not find cpp/string/basic_string_view/begin_end_nonmem in mapping
Could not find cpp/string/basic_string_view/begin_end_nonmem in mapping
Could not find cpp/string/basic_string_view/operator""sv in mapping
Could not find cpp/numeric/complex/operator""i in mapping
Could not find cpp/numeric/complex/operator""i in mapping
Could not find cpp/numeric/complex/operator""i in mapping
Could not find cpp/experimental/fs/filesystem_error/operator= in mapping

The returned status is 0 so it looks like "success", but I am not sure what to make of those messages.

Then make -j$(nproc) all took quite some time and sudo make install, but both succeeded without warning or error messages, so that looks like a success.

However, if I look for any of the items reported above then devhelp seems to find them in the index, but not their content:

So something is missing.

The online version operator""sv has ben modified on 21 September 2021, at 08:42 so this is not exactly new. I would appreciate any pointers where to look for a fix.

Here is how special_math link is represented in output/link_map.xml:

<file from="cpp/experimental/special_functions" to="en/cpp/experimental/special_math.html"/>

Online there are two versions of special math functions:

• cpp/experimental/special_math -- incomplete, obsolete, but present.
• cpp/numeric/special_functions -- complete C++17, which is very cool and I can actually locate them:
  

So this is not important.

Another page: cpp/header/contract has been deleted (probably in favor of concepts), so this is also not important.

Then operator""sv and similar operators are very handy, but there seems to be an issue with escaping quotes resulting in the following line in output/link_map.xml:

<file from="cpp/string/basic_string_view/operator\" to="en/cpp/string/basic_string_view/operator_q__q_sv.html"/>

which is produced by build_link_map.py, where the regular expression on line 51 fails to capture escaped quotes:

m = re.search('"wgPageName":"([^"]*)"', text)

therefore should be replaced with:

m = re.search(r'"wgPageName":"((\\.|[^"\\])*)"', text)

Then the escaped quotes need to be replaced with plain quotes after line 55:

title = m.group(1)
title = title.replace(r'\"', r'"')

Then the produced output/link_map.xml contains &quote; instead of quote character which is correct xml. Then recompile, install and then it works!

Seems like it is not able to set the correct foreground color for text if its unspecified?

For some pages that are modified before preprocess_html_file is run on them, the retrieval time in the footer may be wrong because it shows the modification time of the file.

Could you provide unprocessed archives in the release page since make source is rather slow because connection to cppreference site is slow in my region, and I need to process the archive myself.
What I need indeed is html book made without preprocess.remove_see_also, but it seems improper to ask you to make this version for me. So it will be appreciated if you can provide the source archive and let me process it on demand.

All pages have a script in the head that points to /mwiki/load.php?[...]modules=jquery%2Cmediawiki[...].
This should be adjusted or removed.

Hello @PeterFeicht,

thank you for your recent update. Could you also update cppreference-doxygen-web.tag.xml, because it is missing some of the c++20 keywords that are in the html archive.

Best regards,
marcel

/cc: @h-2

Example on page en/cpp/atomic/memory_order.html under Happens-before.

The background URL in site_modules.css for rule div#content a[href$=".pdf"].external is wrong.

There should be a check to make sure there are no unwanted links to the online version in the output HTML (so things like the broken release v20180527 can't happen again).

The Makefile already has a check target, which would probably be the place to add this to.

When compared to the Qt documentation, cppreference appears to have really large fonts. And the problem is exacerbated with current Qt5 versions which lack QtWebKit, so one can't even scale down the main text: only the caption scales.

The fonts appear correct in the official QCH book release 20170409, and are already too large in the 20181028 release. And this problem remains with the releases made from this repo.

See the following screenshots for comparison between Qt docs and C++ docs.

QString docs @ Qt5 Assistant:

std::string docs @ Qt5 Assistant:

Even if I open in Qt4 Assistant built with QtWebKit support, the fonts are too large, although the content is easier to scale (and formatting is less broken).

std::string docs @ Qt5 Assistant:

The output HTML contains a reference to buysellads.com in a script tag, this should be removed:

<script type="text/javascript">
(function(){
  var bsa = document.createElement('script');
     bsa.type = 'text/javascript';
     bsa.async = true;
     bsa.src = '//s3.buysellads.com/ac/bsa.js';
  (document.getElementsByTagName('head')[0]||document.getElementsByTagName('body')[0]).appendChild(bsa);
})();
</script>

There may be more.

Is it possible to create an epub version of this documentation set for e-readers and apps such as Apple Books? Due to the large amount of HTML files, classical tools such as Pandoc and ebook-convert fail to process the hundreds of individual HTML files present. A script to do this automatically would be greatly appreciated. Thanks for maintaining this invaluable development resource.

Hi, Peter

Thanks for this valuable project. It helps me a lot learning C, C++ programming.

Can we add < prev, next > navigation on each page, so we can read all pages by following the navigation easily, without missing one page.

Hi,

The example code here:
https://en.cppreference.com/w/cpp/string/basic_string_view/substr

uses assignment expressions as arguments: pos = 2, count = 3

It is very confusing, looks like positional parameter or named parameter in Python or Swift. Can we make it simpler?

How can I find the source file in this repo, for the corresponding html web page:
../html-book-20220201/reference/en/cpp/string/basic_string_view/substr.html

Thanks

After:

    std::cout << data.substr() << '\n'; // ABCDEF
    std::cout << data.substr(1) << '\n'; // BCDEF
    std::cout << data.substr(2, 3) << '\n'; // CDE

    std::cout << data.substr(4, 42) << '\n'; // EF
        // count -> 2 == size() - pos == 6 - 4

    try {
        data.substr(666, 1); // throws: pos > size()

Before:

    std::cout << data.substr(pos = 1) << '\n'; // BCDEF
    std::cout << data.substr(pos = 2, count = 3) << '\n'; // CDE
 
    std::cout << data.substr(pos = 4, count = 42) << '\n'; // EF
        // count -> 2 == size() - pos == 6 - 4
 
    try {
        data.substr(pos = 666, count = 1); // throws: pos > size()

The readme states that it is best to download the prepared archive from the website instead of using wget to grab everything. This however is currently not the most up to date version. The published version is from 2019 and thus missing a lot of C++20. There is an published archive in this repo called cppreference-doc- which includes the whole repo with the reference folder included and with the up to date contents.

However the readme doesn't make any suggestion of it's existence nor does it recommend downloading the most recent release and compiling from that. The rest of the documentation makes it seem that this repo is only a compiliation/aggregation tool which always requires user input to work. This isn't true as that release can be used to build everything in one go without the need to download anything else.

Thanks for your work on this first of all!

Even the latest release seems to be missing lots of C++20 stuff, like Concepts and things from std::ranges::. Is this a known issue?

The page refers to the online stylesheet.

Hi!

We are using XML tag file integrated with Doxygen so we can do things like:

/// @see std::vector

This works great for classes and structs, but not for functions, because in the XML tag file the <name> section does not include the std:: prefix, so we need to write:

/// @see begin

Instead of:

/// @see std::begin

Why is that? Would it be possible to add the std:: prefix to all symbols?

Premailer 3.9 added a constructor argument with default value False that causes premailer.premailer.ExternalFileLoadingError when doing "make doc_qch"

From their README.md:

allow_loading_external_files=False # Allow loading any non-HTTP external file URL

Enabling it at commands/preprocess_cssless.py:77 fixes this, but it starts throwing an "unexpected keyword argument" exception when run with premailer <3.9

See release page: https://github.com/PeterFeicht/cppreference-doc/releases/tag/v20190110

qch-book-20190110.tar.xz | 108 Bytes

The link to the online version tries to link to page .../index, which doesn't exist. This needs to be a special case when generating the online version links.

The URL for external link markers (via background CSS style) and the navbar background is relative but not adjusted to the containing file's path, which means the link marker and navbar border will not be visible.

Links to the online version on every page should link to HTTPS, not HTTP.

Hi,

The online search uses google and we can not use that service in the country.

Is it possible to have offline search for local files of cppreference similar to the pgi-doc.

Thanks

https://lazka.github.io/pgi-docs/
https://github.com/pygobject/pgi-docgen

There's at least one script and one style tag for Carbon ads which is not removed during HTML preprocessing (among the first elements in body).