Re: [racket-users] How to fix typos in documentation?

[Ben Greenman]

On 3/8/19, David Storrs  wrote:
> On Fri, Mar 8, 2019 at 3:13 PM Greg Hendershott 
> wrote:
>
>> I have a dumb question. Why can't doc pages have links whose label is
>> something like "Want to improve the docs?", and the URL goes directly
>> to the appropriate .scrbl file on GitHub?
>>
>
> I asked about this a year or so ago and the consensus was that it was
> impractically difficult given the number of tuits that were available at
> the time.  IIRC, it would have required significant changes to the
> documentation generation system.  Perhaps I'm misremembering, or perhaps
> that's changed?

Here's a Scribble issue about adding links to the doc pages:

https://github.com/racket/scribble/issues/76


And here's a Scribble branch that Kieran Hardy and I started (at
RacketCon 2017) to add the links:

https://github.com/bennn/scribble/commits/view-source

Next month I'll try to turn the branch into a pull request. If someone
wants to take the lead this month, feel free.

-- 
You received this message because you are subscribed to the Google Groups 
"Racket Users" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to racket-users+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: [racket-users] How to fix typos in documentation?

[David Storrs]

On Fri, Mar 8, 2019 at 3:13 PM Greg Hendershott 
wrote:

> I have a dumb question. Why can't doc pages have links whose label is
> something like "Want to improve the docs?", and the URL goes directly
> to the appropriate .scrbl file on GitHub?
>

I asked about this a year or so ago and the consensus was that it was
impractically difficult given the number of tuits that were available at
the time.  IIRC, it would have required significant changes to the
documentation generation system.  Perhaps I'm misremembering, or perhaps
that's changed?

-- 
You received this message because you are subscribed to the Google Groups 
"Racket Users" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to racket-users+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: [racket-users] How to fix typos in documentation?

[David Storrs]

Thank you for that writeup, Marc.  I've wanted to offer doc changes several
times but never had the spoons to figure out how.


Matthew, I think you're absolutely right: putting this in a CONTRIBUTING
file would be great.  I've created one and submitted a pull request.  :>

On Fri, Mar 8, 2019 at 11:52 AM Matthew Butterick  wrote:

> Perhaps this would be good material for a CONTRIBUTING.md at the top level
> of the repo, where it would be more likely to be found by future
> contributors. GitHub will automatically show a link to the file at arguably
> appropriate times. [1]
>
> [1] https://github.blog/2012-09-17-contributing-guidelines/
>
> > On Mar 8, 2019, at 8:44 AM, Marc Kaufmann 
> wrote:
> >
> > Let me (ab)use this thread to add some more details on how to submit
> pull requests (PR) on GitHub to racket using the GitHub web interface for
> other noobs - which includes myself in another month or two. Ideally I
> would write this up elsewhere to help with onboarding, but that won't
> happen soon, so here we go. We are talking ELI5 (Explain Like I'm 5) level
> explanations, so this will be painfully obvious to the vast majority
> (although it would be good for someone who knows what they are doing to
> correct whatever kludgy workflow I've come up with). I copy most of the
> steps from Paulo earlier, but add some that I still had to figure out.
>
> --
> You received this message because you are subscribed to the Google Groups
> "Racket Users" group.
> To unsubscribe from this group and stop receiving emails from it, send an
> email to racket-users+unsubscr...@googlegroups.com.
> For more options, visit https://groups.google.com/d/optout.
>

-- 
You received this message because you are subscribed to the Google Groups 
"Racket Users" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to racket-users+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: [racket-users] How to fix typos in documentation?

[Greg Hendershott]

I have a dumb question. Why can't doc pages have links whose label is
something like "Want to improve the docs?", and the URL goes directly
to the appropriate .scrbl file on GitHub?

- A .scrbl file knows its own syntax source file path.
- defmodule forms know how to make links to the package server.
- The package server has a catalog that knows where the source repo is.
- Often it knows, when a pkg is split -{lib doc test}, where the -doc
repo for a -lib is (although ironically "Documentation" for
scribble-lib is blank when I check now.)

Could these elements be combined to provide the direct link on the doc page?

Admittedly people still need to know how to use GitHub and do a PR.
But I think in my own case, the main speed bump feels like finding the
scrbl file to modify. If that were one click, I'd be more likely to
act even on low ROI tiny prose typos I might notice.

On Fri, Mar 8, 2019 at 11:52 AM Matthew Butterick  wrote:
>
> Perhaps this would be good material for a CONTRIBUTING.md at the top level of 
> the repo, where it would be more likely to be found by future contributors. 
> GitHub will automatically show a link to the file at arguably appropriate 
> times. [1]
>
> [1] https://github.blog/2012-09-17-contributing-guidelines/
>
> > On Mar 8, 2019, at 8:44 AM, Marc Kaufmann  wrote:
> >
> > Let me (ab)use this thread to add some more details on how to submit pull 
> > requests (PR) on GitHub to racket using the GitHub web interface for other 
> > noobs - which includes myself in another month or two. Ideally I would 
> > write this up elsewhere to help with onboarding, but that won't happen 
> > soon, so here we go. We are talking ELI5 (Explain Like I'm 5) level 
> > explanations, so this will be painfully obvious to the vast majority 
> > (although it would be good for someone who knows what they are doing to 
> > correct whatever kludgy workflow I've come up with). I copy most of the 
> > steps from Paulo earlier, but add some that I still had to figure out.
>
> --
> You received this message because you are subscribed to the Google Groups 
> "Racket Users" group.
> To unsubscribe from this group and stop receiving emails from it, send an 
> email to racket-users+unsubscr...@googlegroups.com.
> For more options, visit https://groups.google.com/d/optout.

-- 
You received this message because you are subscribed to the Google Groups 
"Racket Users" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to racket-users+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: [racket-users] How to fix typos in documentation?

[Matthew Butterick]

Perhaps this would be good material for a CONTRIBUTING.md at the top level of 
the repo, where it would be more likely to be found by future contributors. 
GitHub will automatically show a link to the file at arguably appropriate 
times. [1]

[1] https://github.blog/2012-09-17-contributing-guidelines/

> On Mar 8, 2019, at 8:44 AM, Marc Kaufmann  wrote:
> 
> Let me (ab)use this thread to add some more details on how to submit pull 
> requests (PR) on GitHub to racket using the GitHub web interface for other 
> noobs - which includes myself in another month or two. Ideally I would write 
> this up elsewhere to help with onboarding, but that won't happen soon, so 
> here we go. We are talking ELI5 (Explain Like I'm 5) level explanations, so 
> this will be painfully obvious to the vast majority (although it would be 
> good for someone who knows what they are doing to correct whatever kludgy 
> workflow I've come up with). I copy most of the steps from Paulo earlier, but 
> add some that I still had to figure out.

-- 
You received this message because you are subscribed to the Google Groups 
"Racket Users" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to racket-users+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: [racket-users] How to fix typos in documentation?

[Marc Kaufmann]

Let me (ab)use this thread to add some more details on how to submit pull
requests (PR) on GitHub to racket using the GitHub web interface for other
noobs - which includes myself in another month or two. Ideally I would
write this up elsewhere to help with onboarding, but that won't happen
soon, so here we go. We are talking ELI5 (Explain Like I'm 5) level
explanations, so this will be painfully obvious to the vast majority
(although it would be good for someone who knows what they are doing to
correct whatever kludgy workflow I've come up with). I copy most of the
steps from Paulo earlier, but add some that I still had to figure out.

--
Long version (even longer version below. The short version is "Submit a PR;
if you need help, submit an Issue". Obviously.)
--

- go to https://github.com/racket/racket.
- Search for "which is one of the collections with its own testing style"
in the repo
- Go the file with the typo
- Edit it by clicking on the 'Edit' button (pen)
1. If you have already forked the repo, you will be asked to choose
another branch. I chose master. (May be bad.)
2. If you never forked it, it will offer "Fork and edit" and create a
temporary branch patch-1 (or patch-n later on)
- Fix the typo
- Add commit message and comment at the bottom, e.g. "Fix broken link" and
"Fixes #2518" (which fixes issue number 2518 conditional on PR being
accepted)
- Hit 'propose file change', and 'commit changes' on next page
- Later, if accepted, you will be able to choose (somewhere in the
conversation part of the PR) to delete the temporary branch 'patch-n' or
what not. Probably a good idea.
- If you are asked to change part of your PR by the maintainers, go to the
PR page, find the last of your commits, choose 'Edit': "change this file in
the online editor"
- This last part seems kludgy. What's the good workflow?

To add an issue:

- Go to https://github.com/racket/racket.
- Go to issues
- Add new issue, write message and comment, check it's not a duplicate
- If you need to add a permalink to a file where the error is, go to the
file, click on line number, click on the [...] that pops up, 'copy
permalink', add to issue message.
- Submit

--
Even Longer version:
--

I'll use the actual example from yesterday: at
https://docs.racket-lang.org/style/testing.html I found the following " See
the 2htdp ,
which is one of the collections with its own testing style" where the 2htdp
link is broken. Let's fix it.

- The documentation is somewhere on github, so go to
https://github.com/racket/racket.
- Type the following into the search bar, but don't yet hit enter: "which
is one of the collections with its own testing style".
- Github will have a pop-up of two search options, one with "In this
repository" and one with "All of Github". Click "in this repository".
- From the hits you get, open the correct file that contains the typo
(click).
- Fix the typo: Magically you know that the link should point to
https://github.com/racket/htdp/tree/master/htdp-test/2htdp
- (I had to submit an issue to find out, I had searched for it with
'2htdp' and some others, but couldn't figure it out. See below on
submitting issues. Thanks to Sam.)
- Finally, you click the pen button at the top for 'Edit', next to 'Raw',
'Blame', 'History'
- Except it says you need to be signed in
- So you log into GitHub (Or you have to sign up.)
- Now you click 'Edit' (pen button)

Two things can happen:

1. You never forked this repository before for an edit or anything.

- You can click the 'Edit' button (pen) (continue this snoozefest below, at
The Adventure Continues)

2. You already forked this project sometime in the past.

- That was my case. It then says "You must be on a branch to make or
propose changes to this file" when I hover over the pen.
- So you scan to the left side, and up (below the 'racket/racket' and '<>
code') to find something saying what branch you are on. Mine had the poetic
'Tree: 5bb83...'
- Click on the dropdown, choose 'master' (I believe that this is the master
branch of my fork. No clue whether this is stupid in general or not - as
in, I don't know whether my master is in sync automatically with
racket/racket master, as I don't know whether forks remain synched without
me doing anything. It worked this time, so ... )
- Click the pen button, and wait until it loads the branch you chose.

The Adventure Continues:

- Finally, edit: change `@hyperlink["
https://github.com/racket/racket/tree/master/collects/2htdp/"]{2htdp}` to
`@hyperlink["https://github.com/racket/htdp/tree/master/htdp-test/2htdp/";
]{2htdp}`
- At the bottom, type in the commit message and additional comments (where
it says "Propose file change")
- I wrote "Update broken URL" and as additional comments "Fixes #2518".
- The latter part means that I claim that this fixes issue number 2518.
I believe that GitHub automatically understands this and if my pull request

Re: [racket-users] Change the order of bibliography entries in Scribble?

[Matthew Flatt]

Ah, I misunderstood. I think there's not currently an option to adjust
the sorting of the bibliography section, but it would make sense to add
one.

At Thu, 7 Mar 2019 23:05:25 -0800, Joey Eremondi wrote:
> Looks like that changes the order the citations are listed at the point of
> citation, but not in the generated bibliography at the end of the document?
> Unless I'm missing something obvious.
> Either way, thanks!
> 
> On Thu, Mar 7, 2019 at 4:36 PM Matthew Flatt  wrote:
> 
> > At Thu, 7 Mar 2019 15:06:30 -0800 (PST), Joey Eremondi wrote:
> > > I'm using Scribble and Frog to automatically generate a publications
> > list
> > > from a BibTex file. The problem is, right now I get the same order
> > > regardless of what order I call ~cite: sorted by year, oldest to newest.
> > > I'd like the reverse of this, with newest at the top. Is it possible to
> > > change the order of the generated bibliography, to either match the
> > order I
> > > call ~cite in, or to automatically sort by date (in reverse?)
> >
> > You can supply `#:sort? #f` as an argument to a `~cite` to use the
> > order that you supply. There's not currently a way to change the
> > automatic sort order.
> >
> > --
> > You received this message because you are subscribed to a topic in the
> > Google Groups "Racket Users" group.
> > To unsubscribe from this topic, visit
> > https://groups.google.com/d/topic/racket-users/4uIjaC1alNU/unsubscribe.
> > To unsubscribe from this group and all its topics, send an email to
> > racket-users+unsubscr...@googlegroups.com.
> > For more options, visit https://groups.google.com/d/optout.
> >

-- 
You received this message because you are subscribed to the Google Groups 
"Racket Users" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to racket-users+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.