1460338 - Migrate symbol server docs from MDN to in-tree

Status: RESOLVED FIXED

(Toolkit :: Crash Reporting, enhancement)

Description

[(not currently active) Ted Mielczarek]

I wanted to make some changes to the symbol server docs on MDN, but MDN is refocusing on just web standards, so Gecko-specific docs don't really belong there anymore. I wrote a little Python script that uses pandoc to convert docs from MDN to rST and used it to import the symbol server docs and it worked pretty well:
https://github.com/luser/convertmdn

They could probably use a little bit of manual cleanup, but it's a good start.

Comment 1

[(not currently active) Ted Mielczarek]

Attachment: bug 1460338 - Migrate symbol server docs from MDN to in-tree.

This patch migrates the symbol server docs from MDN to an in-tree file.
The conversion was done using pandoc by way of my convertmdn script:
https://github.com/luser/convertmdn

Review commit: https://reviewboard.mozilla.org/r/242786/diff/#index_header
See other reviews: https://reviewboard.mozilla.org/r/242786/

Comment 2

[Code Review Bot [:reviewbot]]

Comment on attachment 8974441 [details]
bug 1460338 - Migrate symbol server docs from MDN to in-tree.

https://reviewboard.mozilla.org/r/242786/#review248616


Code analysis found 1 defect in this patch:
 - 1 defect found by mozlint

You can run this analysis locally with:
 - `./mach lint path/to/file` (JS/Python)


If you see a problem in this automated review, please report it here: http://bit.ly/2y9N9Vx


::: toolkit/crashreporter/docs/Using_the_Mozilla_symbol_server.rst:72
(Diff revision 1)
> +your computer, if you'd prefer a different location for downloaded
> +symbols):
> +
> +::
> +
> +    C:\Program Files\Mozilla Firefox>c:\progra~1\debugg~1\symchk.exe /r c:\progra~1\mozill~1\* /s SRV*C:\symcache\*https://symbols.mozilla.org/

Warning: Debugg  ==> debug [codespell]

Comment 3

[Gabriele Svelto [:gsvelto] (PTO)]

Comment on attachment 8974441 [details]
bug 1460338 - Migrate symbol server docs from MDN to in-tree.

https://reviewboard.mozilla.org/r/242786/#review249354

This looks quite good overall but r-'ing it because some parts are mangled in a way that makes the text disappear. Patching them manually is fine if you don't want to make your script more complex.

::: toolkit/crashreporter/docs/Using_the_Mozilla_symbol_server.rst:20
(Diff revision 1)
> +the content of all variables and the execution path can seem strange
> +because of inlining, tail calls, and other compiler optimizations. The
> +only workaround is to build an unoptimized local build.
> +
> +The official symbol server URL for Firefox is
> +``       https://symbols.mozilla.org/     `` . You cannot visit this URL

This appears as an URL, but the backquotes also appear. In this case the backquotes should be removed altogether and the URL will simply work.

::: toolkit/crashreporter/docs/Using_the_Mozilla_symbol_server.rst:24
(Diff revision 1)
> +The official symbol server URL for Firefox is
> +``       https://symbols.mozilla.org/     `` . You cannot visit this URL
> +directly: you must add it to the symbol path of your debugging tool. In
> +the examples below, a local cache directory is used to avoid repeatedly
> +fetching the PDB from the server. Replace
> +``   C:\Users\bsmedberg\symbols  `` with an appropriate cache directory

This causes the backslashes to disappear in the path. The issue seems to boil down to the spaces being present after the double backquotes but before the start of the path. Removing the spurious spaces makes the output looks correct. This same problem happens in other snippets below with double backquotes followed by spaces.

::: toolkit/crashreporter/docs/Using_the_Mozilla_symbol_server.rst:43
(Diff revision 1)
> +asterisk characters. To use only the Mozilla symbol server, add the
> +following entry to your symbol path ( **note:** you can replace c
> +``   :\symcache\  `` with any writable directory on your computer, if
> +you'd prefer a different location for downloaded symbols):
> +
> +.. code:: eval

This is causing the text below to disappear, replacing it with a simple :: solves the issue.

::: toolkit/crashreporter/docs/Using_the_Mozilla_symbol_server.rst:54
(Diff revision 1)
> +would like to get symbols from Microsoft's symbol server as well, you
> +should list that first ( **note:** you can replace c
> +``   :\symcache\  `` with any writable directory on your computer, if
> +you'd prefer a different location for downloaded symbols):
> +
> +.. code:: eval

Likewise.

Comment 4

[Gabriele Svelto [:gsvelto] (PTO)]

Let's finish this work.

Comment 5

[Gabriele Svelto [:gsvelto] (PTO)]

Attachment: Bug 1460338 - Migrate symbol server docs from MDN to in-tree. r?sylvestre

This patch migrates the symbol server docs from MDN to an in-tree file.

Comment 6

[Gabriele Svelto [:gsvelto] (PTO)]

Attachment: Bug 1460338 - Migrate symbol server docs from MDN to in-tree. r?sylvestre

The links and instructions in the page have been updated to reflect the
changes in the symbol server and the old copy was removed. Images have been
recompressed to reduce size.

Comment 7

[Pulsebot]

Pushed by [e-mail]:
https://hg.mozilla.org/integration/autoland/rev/fb353c305f6e
Migrate symbol server docs from MDN to in-tree. r=sylvestre DONTBUILD

Comment 8

[Cosmin Sabou [:CosminS]]

https://hg.mozilla.org/mozilla-central/rev/fb353c305f6e